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About This Book 


This book describes the application programming interface (API) provided by the 
IBM Operating System/2 Extended Edition Version 1.2 Local Area Network 
Requester and IBM Operating System/2 Local Area Network Server Version 1.2 
program (hereafter referred to as the OS/2 LAN Server), which is a separately 
available program that works in conjunction with the LAN Requester component of 
OS/2 Extended Edition Version 1.2 (hereafter referred to as the LAN Requester). 
The API functions are the external functional interface for application program 
development. 


Who Should Use This Book 


This book is intended for use by application programmers and system programmers 
developing software for use in the IBM OS/2 Extended Edition 1.2 local area 
network environment. 


Before You Use This Book 
To use this book effectively, it is recommended that you have a working knowledge 
of the OS/2 program or some other multitasking operating system and that you are 
familiar with application programming in IBM C/2™ language (hereafter referred to 
as C language). 


Note: The OS/2 LAN Requester/Server API functions work in essentially the same 
way for both the IBM OS/2 and IBM DOS operating systems. However, this 
reference specifically addresses the IBM OS/2 programming environment. 


How This Book Is Structured 
This book contains the following chapters: 
Chapter 1, “Overview of OS/2 LAN Server API,” provides an overview of the 
OS/2 LAN Requester/Server API architecture. 


Chapter 2, “Introducing the OS/2 LAN Server API Functions,” includes an 
alphabetical listing of the OS/2 LAN Requester/Server API function categories, 
with brief descriptions and a list of functions in each category. 


Chapter 3, “API Function Descriptions,” describes the OS/2 LAN 
Requester/Server API function categories and the functions in each category. 
Categories and the functions within them are arranged alphabetically. 


Appendix A, “Include Files,” lists each of the include files the OS/2 LAN 
Requester/Server API provides. 


Appendix B, “Function Libraries,” describes the dynamically linked libraries 
that OS/2 LAN Requester/Server uses at link and run time. 


Appendix C, “Return Codes,” describes the API function return codes. 


Appendix D, “Creating OS/2 LAN Server Services,” provides information on 
creating and using network service programs. 


C/2 is a trademark of International Business Machines Corporation. 
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Appendix E, “OS/2 LAN Requester/Server API Support under IBM DOS,” 
describes OS/2 LAN Requester/Server API functions supported by IBM DOS 
along with any differences in their use from that described in Chapter 2. 


Appendix F, “IBM C/2 Sample Program,” contains a sample program for the 
OS/2 LAN Server application programming interface. 


Appendix G, “PC LAN Program 1.3 Compatibility,” provides several function 
calls for compatibility with applications currently supported by PCLP 1.3. 


Appendix H,“LAN API Manifests,” lists the manifests associated with ASCIIZ 
strings that are pointed to by data structure components used in the OS/2 LAN 
API. 


A glossary describes specialized terms used in this book. 


An index is included at the back of the book. 


Conventions 
Throughout this book, the following conventions distinguish elements of text: 
Text Element Use 
bold Command names, switches, and literal 


portions of syntax that must be written 
exactly as shown are bold within text 

paragraphs. (No text styles are applied 
to elements within monospace entries.) 


italics Variable text representing a type of text 
to be entered rather than a literal series 
of characters are in italics within text 
paragraphs. 


Italic type is also used to introduce new 
terms and, occasionally, for emphasis. 


monospace Data structures and function syntax 
templates are monospace, as are any 
sample program lines within text 
sections. 


CAPITALS File names and acronyms are in 
capitals. 
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Related Publications 


The IBM OS/2 LAN Requester/Server documentation set includes other manuals 
that may be helpful to you. For information on installing, using, or administering 
OS/2 LAN Requester/Server, consult the following publications: 


¢ IBM Operating System/2 Local Area Network Server Version 1.2 Getting Started 


¢ IBM Operating System/2 Local Area Network Server Version 1.2 Network 
Administrator's Guide 


¢ IBM Operating System/2 Local Area Network Server Version 1.2 User's Guide 
¢ IBM Operating System/2 Programming Guide 


e IBM Operating System/2 Technical Reference Version 1.2 Programming 
Reference. 
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LAN Server Application Programmer’s Reference 


Chapter 1. Overview of OS/2 LAN Server API 


This chapter introduces the OS/2 LAN Requester/Server 1.2 application 
programming interface (API), which is a set of functions enabling application 
programs to interact with and to control network operations and resources. In this 
chapter, you will find information about: 


¢ The organization of and naming conventions for OS/2 LAN Requester/Server 
API functions 


¢ The API data structures and the way they accept and return information 
e The API security scheme 

¢ The protection violations and faults in the dynamic link libraries 

e The local and remote function calls 

e The requirements for calling API functions 

e The naming conventions for network names. 


Note: The API functions shown are for use with C language. 


Organization of OS/2 LAN Server API Functions 


The OS/2 LAN Requester/Server API provides access to the network functions 
through a well-defined interface for high-level languages. This interface defines the 
name of a function depending on the task that the function performs. 


The OS/2 LAN Requester/Server API naming convention divides each function into 
three parts: 


e The Net, Dos, or Spl keyword identifies the function as an OS/2 LAN 
Requester/Server API function or an OS/2-compatible function. 


e A category identifier indicates the software area in which the function performs. 
For example, User identifies functions that control user accounts. 


This identifier may be compound, as in ServerDisk, which identifies the function 
of server disk tasks. Generally, but not always, the identifier correlates to a 
function category. The notable exception is the Named Pipe category, which 
contains a broad category of OS/2 functions. 


e A verb describes the action the function performs. 


An optional fourth part in function names works somewhat as a direct object would 
in the English language, identifying a particular object to be involved in the action. 
For instance, NetCharDevQPurgeSelf deletes all pending requests waiting in a serial 
device queue that were submitted by a particular computer, whereas 
NetCharDevQPurge deletes all pending requests on a serial device queue. 
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AP! Verbs 


Add Functions 


Del Functions 


The OS/2 LAN Requester/Server software defines a set of verbs for each category of 
functions. The five most common verbs perform the following basic tasks: 


Verb Action 

Add Adds a resource 

Del Deletes a resource 

Enum Lists the names and data structures for 
a resource 

GetInfo Retrieves parameters for a resource 

SetInfo Modifies parameters for a resource 


The less common verbs perform other tasks relating to specific resources, such as 
starting a service (Install) or deleting pending requests on a queue (Purge). 


The five most common OS/2 LAN Requester/Server API verbs use fairly standard 
syntax and parameters. These operations, which are described in the following 
sections, comprise the basic set of function tasks for most categories. 


An Add function adds a resource to a particular set of items. Add functions 
generally use some form of the following syntax: 


unsigned far pascal 
NetExampleAdd (servername, level, buf, buflen) 


char far * servername ; 
short level; 
char far * buf ; 


unsigned short buflen; 


where: 


° servername points to an ASCIIZ string containing the name of the remote server 
(preceded by a double backslash (\\) or a double forward slash (//)) on which the 
function is to execute. A NULL pointer or string specifies a local computer. 


¢ level specifies a data structure providing a particular level of detail of 
information required to complete the operation. 


¢ buf points to the data structure. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


A Del function removes a resource from a particular set of items. Del functions 
generally use some form of the following syntax: 


unsigned far pascal 
NetExampleDel (servername) 
char far * servername; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
(preceded by a double backslash (\\) or a double forward slash (//)) on which the 
function is to execute. A NULL pointer or string specifies a local computer. 
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Enum Functions 


Del functions do not require a pointer to a data structure since they do not accept or 
return the kind of information commonly found in data structures. 


An application must have administrative privileges to remotely execute most Del 
functions. 


The Enum functions list information about system resources. Enum functions 
generally use some form of the following syntax: 


unsigned far pascal 
NetExampleEnum (servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
(preceded by a double backslash (\\) or a double forward slash (//)) on which the 
function is to execute. A NULL pointer or string specifies a local computer. 


e level specifies the level of detail for the returned data. 
e buf points to the returned data structures. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
available. 


If buf cannot store all returning data, the Enum function returns the 
NERR_ MORE DATA error code. There is an entriesread number of items returned 
in the buffer. 


If the value of buflen is 0, the Enum function returns only a valid totalentries 
parameter. 


Some requests for high levels of detail by way of Enum functions require 
administrative privileges at the remote server. 


Enum functions are limited to 64KB per call. 
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Getinfo Functions 


Setinfo Functions 


A GetInfo function retrieves specific information about a resource not available to 
an Enum function. These functions generally use some form of the following syntax: 


unsigned far pascal 
NetExampleGetInfo (servername, level, buf, buflen, totalavail) 


char far * servername, 
short levels 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 


where: 


° servername points to an ASCIIZ string containing the name of the remote server 
(preceded by a double backslash (\\) or a double forward slash (//)) on which the 
function is to execute. A NULL pointer or string specifies a local computer. 


¢ level specifies the level of detail that the data structure is to return. 
¢ buf points to the returned data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information available, given sufficient buflen. 


If buf cannot store all returning fixed-length data, GetInfo returns the 
NERR_BufTooSmall error code. In this case, all data in buf is not valid, but 
totalavail is valid. 


If buf can store all returning fixed-length data but not all available variable-length 
data, GetInfo returns the ERROR_MORE _DATA error code. In this case, the 
fixed-length data in buf is valid, with pointers to any incomplete variable-length data 
set to NULL. If the value of buflen is 0, the GetInfo function returns only a valid 
totalavail parameter. 


Some requests for high levels of detail by way of GetInfo functions require 
administrative privileges. 


A SetInfo function sets the parameters of a network resource. These functions 
generally use some form of the following syntax: 


unsigned far pascal 
NetExampleSetInfo (servername, level, buf, buflen, parmnum) 
char far * servername; 


short level; 
char far * buf; 
unsigned short _buflen; 
short parmnum; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
(preceded by a double backslash (\\) or a double forward slash (//)) on which the 
function is to execute. A NULL pointer or string specifies a local computer. 


¢ level specifies the level of detail that the data structure is to provide. 
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¢ buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines whether an entire data structure or a single data structure 
component is to be set. If the value is 0, a complete data structure must be 
provided. Otherwise, parmnum should specify the ordinal position of a specific 
data structure component to be set. 


For information on the ordinal position of a component, see the appropriate 
include file of the function. 


Error Return Codes 
In the functional description of each API, there is a list of possible return codes. 
Following that is a list of low-level functions it calls from which errors might be 
returned directly. If some errors from an API are ignored or mapped to other APIs, 
the ignored error codes are listed in brackets [] with a minus sign, such as the 
following: 


DosOpen [- ERROR_FILE_NOT_FOUND] 


This example indicates that DosOpen is called, and all error codes from DosOpen 
are possibly returned to the caller, except for ERROR_FILE_NOT_FOUND, which 
is returned by the network API. 


The redirector is called by way of special IOCtls and FSCtls, which are represented 
variously as follows: 


redir. IOCTLCALLNAME 
DosFSCt1 (IOCTLCALLNAME) 
Dos IOCTL(IOCTLCALLNAME) 


When an API is executed remotely without having the necessary permissions or 
authorization, it results in the error code ERROR_ACCESS DENIED. This is a 
consistent error across all APIs for remote calls. An attempt to execute an API 
remotely may return ERROR NETWORK ACCESS DENIED, indicating that 
there was some error in the transportation of the request, rather than an API 
permission or authorization violation. 


API Data Structures 


Most API functions use one or more OS/2 LAN Requester/Server-defined data 
structures to provide or return information defining a resource or reporting its state. 


Distinct structures are defined for each category. They use the C language syntax 
and are WORD-aligned. 


Structuring Levels of Detail 
The functions in the various API function categories provide different levels of 
detail, each represented by a different data structure. The more detailed structures 
usually include all the information in lower-level structures. 


When an API function can provide or return more than one level of information, an 
application must pass a /evel parameter (0, 1, 2, 3 or 10) to indicate the level of 
detail requested. Level 0 is the least detailed (often a single component), with each 
subsequent level calling for more detail. 
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The related /evel parameter is included in the data structure name. For instance, the 
NetShareGetInfo function uses the share_info_0, share_info_1, and share_info_2 data 
structures for data detailed at the 0, 1, and 2 levels, respectively. 


Many functions, particularly the SetInfo type, require a particular data structure 
specified by a particular level value. If an unacceptable Jevel parameter is passed, the 
function returns the ERROR_INVALID_LEVEL error code. 


Sample Data Structures 


The three data structures of the NetShareGetInfo function illustrate the levels of 
detail an API function can provide. The share_info_0 data structure returns only the 
netname of a particular resource. NetShareEnum returns a set of these structures—a 
list containing the names of all resources shared on the server: 


struct share_info_0 { 
char shi0_netname[NNLEN+1] ; 
}3 


The share_info_] data structure returns the name of the shared resource, parameters 
indicating the type of resource, and an optional remark provided by way of the 
NetShareSetInfo function when the share is added on the server (NetShareSetInfo, 
for obvious reasons, requires a level 1 or 2 data structure). 


NetShareEnum, at level 1, returns a set of share_info_1 structures—one for each 
resource shared on the server: 


struct share_info_l { 


char shil_netname[NNLEN+1] ; 
char shil_pad1; 
unsigned short shil_type; 
char far * shil_remark; 
}; 


The share_info_2 data structure adds information on the permissions, path name, 
number of current uses, and password for a share to the level 1 data structure: 


struct share_info 2 { 


char shi2_netname[NNLEN+1] ; 
char shi2_pad1; 
unsigned short shi2_type; 
char far * shi2_remark; 
unsigned short shi2_permissions; 
unsigned short shi2_max_uses; 
unsigned short shi2_current_uses; 
char far * shi2_path; 
char shi2_passwd[SHPWLEN+1] ; 
char shi2_pad2; 

}s 


Storing Fixed-Length and Variable-Length Data 


When the application is passing a data structure in a buffer to the API, if the data 
structure has pointers to variable-length data, the buffer length should be the length 
of the fixed-length portion only. The fixed-length data and the variable-length data 
do not have to be contiguous in the same memory region, even for remote calls. 


When a data structure that defines a pointer to variable-length data (such as ASCIIZ 
strings) is passed to or returned by a function, an application must provide a buffer 
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large enough to store both the fixed-length and variable-length data. Otherwise, not 
all of the data can be passed or returned. 


If a buffer is too small to hold all variable-length data associated with a structure, an 
application should notify the function that no variable-length data is being passed by 
specifying NULL pointers to the variable-length data. 


If an application calls a function that could return more variable-length data than 
the buffer can store, the function returns as much data as possible, setting all 
pointers to information that was not returned to NULL. In this case, the function 
also returns the ERROR_MORE DATA error code and the number of bytes 
required to store all available data (the bytesavail value). If the buffer is too small 
for the fixed-length data, the function returns NERR_BusTooSmall or 
ERROR_MORE_DATA and the amount of data that can fit into the buffer. 


API Security Scheme 


The OS/2 LAN Server security scheme assigns privilege levels to users. Certain API 
functions are designated admin or partially admin. These are available only to users 
with administrative privileges. These APIs retrieve or set sensitive data or control 
key network services. OS/2 LAN Requester/Server provides the following types of 
protection at the API level: 


e Administrative privilege 


e Security for remote API function calls. 


The access control subsystem (ACS) controls the domain-wide access of resources by 
the users and groups. The users and groups management and resource access 
control at the API level is called the user accounts subsystem (UAS) database. 


Remote Protection 
All of the APIs can be executed on a local system, provided that the required 
software services are running. Ordinary users are treated as administrators locally 
on the application programming interface. 


The API calls to remote servers are subject to privilege checking. Many of the APIs 
require administrative privilege to run on remote servers. 


User Interface and Application Programming Interface 
The OS/2 LAN Requester/Server provides user-level security. Share-level security is 
not supported. The user is required to be logged on in order to run utilities, 
applications, or user interface programs remotely. 


Protection Violations and Faults in the Dynamic Link Libraries 


The API functions probe the buffers passed to them and scan string parameters in an 
attempt to ensure that the data is accessible. These probes may cause faults if the 
pointers are incorrect (for example, if they are pointing beyond the end of a segment 
or outside a permitted memory region). 


If you get a fault within an OS/2 LAN Requester/Server dynamic link library, 


attempt to trace the code through the call. By noting the values that are being tested, 
you can usually recognize the parameter that is causing the problem. Also, check 
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buffer sizes carefully, since the API functions probe the first and last byte of a buffer 
even if the data returned or received does not fill the buffer. 


If you get a stack overflow, extend the stack size. There is no hard and fast rule for 
determining the depth of stack that an OS/2 LAN Requester/Server API function 
requires. Generally, allow 4KB of free stack space for each function call. 


Local and Remote Function Calls 


All OS/2 LAN Requester/Server API functions can be executed on a local server. 
Many functions can also be executed on a remote server or a local requester. 
Functions that can be executed remotely supply the name of an accessible remote 
server for the servername parameter. A NULL servername parameter (either a 
NULL pointer or a NULL string) executes the function locally. 


Administrative, Local, and Server APIs 
Certain OS/2 LAN Requester/Server API functions can be called only at the 


administrative, local, or server level. These requirements are noted in parentheses 
after function titles in the following format: 


NetExampleFunction ([partially ] admin, local, Server, DOS [only]) 


These requirements have the following meanings: 


API Requirement Meaning 

admin Can execute remotely only if the calling 
process has administrative privileges in 
the domain. 

partially admin Can execute with user privilege on 


certain level of data structures or user’s 
own information. 


local Can execute only on the local computer. 

server Can execute only on a computer 
running server software. 

DOS Can execute both under OS/2 and DOS 
requesters. 


When administrative privilege for an operation is inadequate, the function returns 
the error message ERROR_ACCESS_DENIED. 


DOS LAN Requester Considerations 


When porting OS/2 LAN Requester/Server applications to run under DOS, note that 
DOS, unlike the OS/2 program, does not support pointer checking, semaphores, or 
shared memory segments. Also, note that all file names, directory names, or parts of 
a path name, including UNC server and network names, must follow DOS naming 
conventions. 
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Network Naming Conventions 


The OS/2 LAN Requester/Server API defines name formats (ASCIIZ strings) to 
distinguish various parts of the network software. Thus, an API function can easily 
distinguish the type of resource or device parameter that is being passed. 


The server name must be preceded by a double back or forward slash (\\ or //). 


The format and maximum length of each type of name are defined in the 
NETCONS.H include file. 


The OS/2 LAN Server Version 1.2 API supports OS/2 Extended Edition Version 1.2 
file names. For OS/2 LAN Server version 1.2, the OS/2 program limits fully specified 
paths to 260 characters, including the following: 


e The drive letter 
¢ The colon (:) 


e All of the characters in the path name, including all backslashes (\) and slashes 


(/) 
¢ The file or directory name on the end of the path 


¢ The null character on the end of the path. 


For OS/2 LAN Server Version 1.2, the operating system limits component names 
to 255 characters. A component name is a file name or directory name (or a 
psuedo directory name). It is the part of a path between the two backslashes or 
between a slash and the null character on the end of the path. The 255 
characters include all of the characters in the component name, but do not 
include the backslashes or the ending null character. 


All characters can be used in network names except ASCII characters less than 
hexadecimal 20 and the following: 

Be [J:|l|<>+=3, 

Spaces are not allowed in domain names. 

Periods can be used; however, they cannot be the first character of a network name 
or immediately follow another period in a name. For example, 

work.sta.1 


is valid because a period does not start the name and the second period does not 
immediately follow the first use of a period. But 


.work.sta.1 
and 
work..sta.l 


are not valid because of a period at the beginning of a name and the two periods 
used together. 
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Chapter 2. Introducing the OS/2 LAN Server API Functions 


This chapter contains a categorical list of the OS/2 LAN Requester/Server API 
functions, giving a brief description of the action performed by each function. 


For detailed descriptions of the OS/2 LAN Requester/Server API functions, see 
Chapter 3, “API Function Descriptions.” 


Function Categories 


Twenty-four categories of API functions perform various OS/2 LAN 
Requester/Server network tasks. For example, the Serial Device category contains 
all functions that are used to control shared serial devices. In the descriptions that 
follow, both the categories and the functions within each category are listed 
alphabetically. The function name is followed by an italicized label in parentheses, 
which describes when the function can be successfully called. For example, the 
NetShareAdd function can be executed only by an application with administrative 
privileges on a server. 


Note: The function names are shown as they should be used in a C language 
program; that is, the function names must be entered in uppercase and 
lowercase letters. 


Access Permission 
The functions in the Access Permission category examine or modify user or group 
access permission records for server resources. 


Function Description 


NetAccessAdd (admin, DOS) Creates an access permission record 
assigning user and group permissions 
for a new resource. 


NetAccessCheck (local) Verifies a user’s or group’s permission 
to access a particular resource. 
NetAccessDel (admin, DOS) Deletes all access permission records for 
a particular shared resource. 
NetAccessEnum (admin, DOS) Enumerates all access permission 
records for a particular server resource. 
NetAccessGetInfo (admin, DOS) Retrieves information about an access 
permission record for a resource. 
NetAccessGetUserPerms (partially Supplies a specified user or group 
admin, DOS) permission fcr a resource. 
NetAccessSetInfo (admin, DOS) Modifies an access permission record 


for a resource. 
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Alert 


The functions in the Alert category provide a system for notifying network service 
programs and applications of network events. 


Function 


NetAlertRaise (local) 
NetAlertStart (Jocal) 


NetAlertStop (local) 


Auditing 


Description 


Notifies all clients registered in the alert 
table that a particular event occurred. 


Registers a client to be notified of a 
particular type of network event. 


Removes a client registration from an 
alert table. 


The functions in the Auditing category control the audit log file, which contains an 
audit trail of operations that occur on a server. 


Function 
NetAuditClear (admin, DOS) 


NetAuditRead (admin, DOS) 


NetAuditWrite (local, server) 


Configuration 


Description 


Clears (and optionally saves) the audit 
log file of a server. 


Opens and returns an OS/2 file handle 
to the audit log file of a server. 


Writes an audit trail entry to the local 
audit log file. 


The functions in the Configuration category retrieve network configuration 


information from the IBMLAN_INI file. 


Function 


NetConfigGet2 (admin, DOS) 


NetConfigGetAll2 (admin, DOS) 


Connection 


Description 


Retrieves a specified parameter value for 
a given network component in the 
IBMLAN.INI file from a remote 
computer. 


Retrieves all parameter information for 
a given network component in the 
IBMLAN.INI file from a remote 
computer. 


The NetConnectionEnum function gives a listing of all connections made to a server 
by a requester client or all connections made to the shared resource of a server. 


Function 


NetConnectionEnum (admin, server, 
DOS) 
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Description 


Lists either all connections between 
requesters and resources on a server or 
all connections established within a 
session. 


Domain 


Error Logging 


File 


Group 


The functions in the domain category provide domain-wide information. 


Function 
NetGetDCName (DOS) 


NetLogonEnum (partially admin, DOS) 


Description 


Obtains the name of the domain 
controller. 


Supplies information about logged on 
users. 


The functions in the Error Logging category control the error log file. 


Function 


NetErrorLogClear (admin) 


NetErrorLogRead (admin) 


NetErrorLogWrite (local) 


Description 


Clears (and optionally saves) an error 
log file. 


Opens and returns an OS/2 file handle 
to the error log file of a computer. 


Writes an entry to the error log file of a 
computer. 


The functions in the File category provide a system for monitoring the file, device, 
and pipe resources that are opened on a server, and for closing one of these 


resources if necessary. 
Function 
NetFileClose2 (admin, server, DOS) 


NetFileEnum2 (admin, server, DOS) 


NetFileGetInfo2 (admin, server, DOS) 


Description 


Forces a resource closed when a system 
error prevents a normal DosClose 
function closing. 


Allows the user to issue iterated calls to 
get information about some or all open 
files on a server. 


Retrieves information about a particular 
opening of a server resource. 


The functions in the Group category control user groups in the user accounts 


subsystem (UAS) database. 


Function 

NetGroupAdd (admin, DOS) 
NetGroupAddUser (admin, DOS) 
NetGroupDel (admin, DOS) 


NetGroupDelUser (admin, DOS) 


Description 
Creates a new group account. 
Adds a user to a group. 


Removes a group account from the 
UAS database. 


Removes a user from a particular 
group. 
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Function 
NetGroupEnum (partially admin, DOS) 


NetGroupGetInfo (partially admin, 
DOS) 


NetGroupGetUsers (partially admin, 
DOS) 


NetGroupSetInfo (admin, DOS) 
NetGroupSetUsers (admin, DOS) 


Handle 


Description 
Lists all group accounts. 


Obtains group-related information. 
Lists the members of a particular group. 
Sets group-related information. 


Sets information about users who 
belong to a group. 


The functions in the Handle category obtain and set information on a per-handle 


basis. 


Function 
NetHandleGetInfo (local, server) 
NetHandleSetInfo (local, server) 


Mailslot 


Description 
Obtains handle-specific information. 


Sets information in the data structure of 
a handle. 


The functions in the Mailslot category provide one-way interprocess communication 


(IPC). 


Function 


DosDeleteMailslot (local, DOS) 


DosMailslotInfo (local, DOS) 
DosMakeMailslot (local, DOS) 
DosPeekMailslot (local, DOS) 


DosReadMailslot (local, DOS) 


DosWriteMailslot (local, DOS) 
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Description 


Deletes a mailslot, discarding all 
messages, whether or not they have been 
read. 


Returns information about a particular 
mailslot. 


Creates a mailslot and returns its 
handle. 


Reads the next message in a mailslot 
without removing any data. 


Reads, then removes the most current 
message from a mailslot (based on 
priority). 


Writes a message to a particular 
mailslot. 


Named Pipe 


The functions in the Message category are used to send, log, and forward messages. 


Function 
NetMessageBufferSend (admin, DOS) 


NetMessageFileSend (admin, DOS) 


NetMessageLogFileGet (admin, DOS) 


NetMessageLogFileSet (admin, DOS) 


NetMessageNameAdd (admin, DOS) 


NetMessageNameDel (admin, DOS) 


NetMessageNameEnum (admin, DOS) 


NetMessageNameFwd (admin) 


NetMessageNameGetInfo (admin, DOS) 


NetMessageNameUnFwd (admin) 


Description 


Sends a buffer of information to a 
registered user on a particular computer. 


Sends a file to a registered user on a 
particular computer. 


Retrieves the name of the message log 
file and the current logging status (on or 


off). 


Specifies a file to log messages received 
by registered users and enables or 
disables logging. 


Registers a user in the message-name 
table. 


Deletes a user name from a 
message-name table. 


Lists the user name entries in a 
message-name table. 


Modifies the message-name table to 
forward a user’s messages to another 
user. 


Retrieves information about a user’s 
message account. 


Stops forwarding a user’s messages to 
another user. 


The functions in the Named Pipe category control interprocess communication (IPC) 
for named pipes. These functions are provided by the base operating system and 
supported by the OS/2 LAN Server across the network. 


Function 
DosBufReset (local, DOS) 
DosCallNmPipe (local, DOS) 


DosClose (local, DOS) 


DosConnectNmPipe (local) 


DosDisconnectNmPipe (local) 


DosDupHandle (local, DOS) 


Description 
Clears the data buffer of a named pipe. 


Opens a named pipe, performs a write 
to the pipe followed by a read, and then 
closes the pipe. 


Closes a named pipe. 


Waits for a client process to open an 
instance of a named pipe. 


Forces a named pipe to close, denying a 
client process any further access to it. 


Duplicates the handle to a named pipe. 
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Function 


DosMakeNmPipe (local) 


DosOpen (local, DOS) 


DosPeekNmPipe (local, DOS) 


DosQFHandState (local, DOS) 


DosQHandType (/ocal, DOS) 
DosQNmPHandState (local, DOS) 


DosQNmPipelnfo (Jocal, DOS) 


DosQNmPipeSemState (local) 


DosRead (local, DOS) 


DosReadAsync (local) 


DosSetFHandState (local, DOS) 


DosSetNmPHandState (/ocal, DOS) 


DosSetNmPipeSem (local) 


DosTransactNmPipe (local, DOS) 


DosWaitNmPipe (/ocal, DOS) 


DosWrite (local, DOS) 
DosWriteAsynce (local) 
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Description 


Creates a new named pipe or a new 
instance of an existing named pipe and 
returns its handle. 


Opens the client process end of a named 
pipe and returns a handle. 


Reads the data in a named pipe without 
removing it. 


Retrieves information about whether the 
handle of a named pipe is inheritable 
and whether write-behind to remote 
pipes is allowed. 


Returns the type of a particular handle. 


Returns information about the current 
state of a named pipe. 


Retrieves information about the sizes of 
the incoming and outgoing buffers of a 
named pipe and the number of instances 
that are available. 


Returns information about the status of 
a semaphore associated with a named 
pipe on a local computer. 


Reads data from a named pipe. 


Reads data from a named pipe 
asynchronously, removing the data. 


Modifies the open mode state of a 
named pipe. 


Modifies the read mode and blocking 
mode state of a named pipe. 


Associates a semaphore with the client 
or server process of a local named pipe. 


Writes a message to and then reads a 
message from a named pipe. 


Enables a client process to wait for an 
available instance of a named pipe. 


Writes data to a file or named pipe. 


Writes data to a named pipe 
asynchronously. 


Remote Utility 


Requester 


Serial Device 


The functions in the Remote Utility category enable applications to copy and move 
remote files, remotely execute a program, and access the time-of-day information on 


a remote server. 


Function 


NetRemoteCopy (local, DOS) 


NetRemoteExec (local, server) 


NetRemoteMove (local, DOS) 


NetRemoteTOD (DOS) 


Description 


Copies one or more files from one 
location to another. 


Executes a program located on a remote 
server. 


Moves one or more files from one 
location to another. 


Returns time of day on a server. 


The functions in the Requester category control the operation of requesters. 


Function 


NetWkstaGetInfo (partially admin, 
DOS) 


NetWkstaSetInfo (admin, DOS) 
NetWkstaSetUID2 (admin, DOS) 


Description 


Returns information about the 
configuration components of a 
requester. 


Configures a requester. 


Registers a user name and password 
with the redirector to validate the user 
account. 


The functions in the Serial Device category control shared serial devices and their 


associated queues. 


Function 


NetCharDevControl (admin, server, 
DOS) 


NetCharDevEnum (admin, server, DOS) 
NetCharDevGetInfo (server, DOS) 
NetCharDevQEnum (server, DOS) 
NetCharDevQGetInfo (server, DOS) 
NetCharDevQPurge (admin, server, 


DOS) 
NetCharDevQPurgeSelf (server, DOS) 


Description 


Forces a serial device to close. 


Lists all serial devices in a shared serial 
device queue on a server. 


Retrieves information about a particular 
serial device in a shared serial device 
queue on a server. 


Lists all serial device queues on a server. 


Retrieves information about a particular 
serial device queue on a server. 


Deletes all unprocessed requests on a 
serial device queue. 


Deletes all pending requests waiting in a 
serial device queue submitted by a 
particular computer. 
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Server 


Service 


Session 


Function 


NetCharDevQSetInfo (admin, server, 
DOS) 


Description 


Modifies the state of a serial device 
queue on a server. 


The functions in the Server category enable remote administrative tasks to be 


performed on a local or remote server. 


Function 


NetServerAdminCommand (admin, 
server, DOS) 


NetServerDiskEnum (admin, DOS) 
NetServerEnum2 (DOS) 
NetServerGetInfo (partially admin, 


server, DOS) 
NetServerSetInfo (admin, server, DOS) 


Description 


Executes a command on a server. 


Retrieves a list of local disk drives on a 
computer. 


Enumerates the set of all machine IDs 
visible on the network. 


Retrieves information at one of four 
levels of detail about a particular server. 


Sets the operating parameters for a 
server. 


The functions in the Service category start and control network service programs. 


Function 


NetServiceControl (partially admin, 
DOS) 


NetServiceEnum (DOS) 


NetServiceGetInfo 


NetServiceInstall (admin, DOS) 


NetServiceStatus 


Description 


Controls the operations of network 
SEIVICeS. 


Retrieves information about all network 
services started on a server or a 
requester. 


Retrieves information about a particular 
started network service. 


Starts a network service on a server. 


Sets status and code information for a 
network service. 


The functions in the Session category control network sessions established between 


requesters and servers. 
Function 


NetSessionDel (admin, server, DOS) 


NetSessionEnum (partially admin, server, 
DOS) 
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Description 


Ends a session between a requester and 
a server. 


Provides information on all current 
sessions to a server. 


Share 


Spooler 


Function 


NetSessionGetInfo (partially admin, 
server, DOS) 


Description 


Retrieves information about a session 
established between a particular 
requester and server. 


The functions in the Share category control shared resources. 


Function 
NetShareAdd (admin, server, DOS) 
NetShareCheck (server, DOS) 


NetShareDel (admin, server, DOS) 


NetShareEnum (partially admin, server, 
DOS) 


NetShareGetInfo (partially admin, 
server, DOS) 


NetShareSetInfo (admin, server, DOS) 


Description 
Creates a shareable resource. 


Queries whether a server is sharing a 
device. 


Deletes a netname from shared 
resources. 


Retrieves share information about each 
shared resource. 


Retrieves information about a particular 
shared resource. 


Sets a new share parameter or 
parameters for a shared resource. 


The functions in the Spooler category provide applications access to spooler queue 
manager operations. These functions are provided by the base operating system and 
supported by the OS/2 LAN Server across the network. 


Function 
SplQmAbort 


SplQmClose 


SplQmEndDoc 


SplQmOpen 


SplQmStartDoc 
SplQmWrite 


Description 


Stops the generation of the spool files 
and automatically closes the spooler 
queue manager. 


Closes the spooler queue manager. 


Ends a print job and returns a unique 
job number. 


Opens the spooler queue manager for 
generating a print job. 


Signifies the start of a print job. 


Writes a buffer to the spool file for the 
print job. 
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Statistics 


The functions in the Statistics category retrieve and clear the operating statistics for 


requesters and servers. 


Function 
NetStatisticsGet2 (admin, DOS) 


Use 


Description 


Obtains and optionally clears the 
operating statistics for a server. 


The functions in the Use category examine or control connections (uses) between 


requesters and servers. 


Function 
NetUseAdd (admin, DOS) 


NetUseDel (admin, DOS) 


NetUseEnum (admin, DOS) 


NetUseGetInfo (admin, DOS) 


User 


Description 


Establishes a connection between a local 
or NULL device name and a shared 
resource by redirecting the local or 
NULL universal naming convention 
(UNC) device name to the shared 
resource. 


Ends a connection between a local or 
UNC device name and a shared 
resource. 


Lists all current connections between the 
local requester and resources on a 
remote server. 


Retrieves information about a 
connection between a local device and a 
shared resource. 


The functions in the User category control a user’s account in the UAS database. 


Function 
NetUserAdd (admin, DOS) 


NetUserDel (admin, DOS) 
NetUserEnum (partially admin, DOS) 


NetUserGetGroups (partially admin, 
DOS) 


NetUserGetInfo (partially admin, DOS) 
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Description 
Adds a user to the set of those 


permitted to use the resources of a 
server. 


Removes a user’s account from the 
UAS database, ending the user’s access 
to the resources of the server. 


Returns information about all user 


accounts. 


Lists all groups on a server to which a 
particular user belongs. 


Retrieves information about a particular 
user account. 


Function 
NetUserModalsGet (partially admin, 
Dos) 


NetUserModalsSet (admin, DOS) 


NetUserPasswordSet (DOS) 


NetUserSetGroups (admin, DOS) 


NetUserSetInfo (partially admin, DOS) 


NetUserValidate2 (local) 
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Description 


Obtains global modals-related 
information for all users and groups in 
the UAS database. 


Sets global modals-related information 
for all users and groups in the UAS 
database. 


Changes the password in a user’s 
account. 


Sets the groups of which a user is 
member. 


Modifies permission information about 
a particular user name. 


Validates a user ID with its password 
and verifies that the user can log on 
based on logon restrictions defined for 
the account. 
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Chapter 3. API Function Descriptions 


This chapter provides detailed information about the syntax of each API function, 
the tasks that the function performs, and data structures. and header files that it uses. 
This chapter includes twenty-four reference sections, each representing one of the 
twenty-four function categories outlined in Chapter 2, “Introducing the OS/2 LAN 
Server API Functions.” 


Format of API Reference Pages 


Each function category begins with an overview explaining how the functions 
interrelate and how they work with the network software. Any data structures 
common to several or all of the functions are then described. Each category 
contains a separate reference section for each function. In the reference section, 
syntax is described and parameters are defined. Error codes returned by the 
function are listed and briefly described. In most cases, a discussion expanding on 
function requirements or behaviors not previously covered is also included. 


Both the function categories and the function reference sections within them are 
ordered alphabetically. 


The following subsections describe the type of information that can be found on the 
individual API reference pages: 


Title Briefly describes why, how, or when your application should 
use the function. The function title is followed by a brief 
description of the use of the function. A complete list of 
function restrictions is described in Chapter 2, “Introducing 
the OS/2 LAN Server API Functions.” 


Syntax Describes the header files that must be included before your 
application calls the function. In addition, it provides the 
definition of the function and a detailed description of the 
parameters of each function. 


Return Codes Provides a list of the return codes the function is most likely 
to return. This list is not exhaustive. Low-level operating 
system conditions may return other codes. For a complete 
listing of OS/2 LAN Requester/Server error codes, see 
Appendix C, “Return Codes.” 


Remarks Describes important details about the performance of the 
function or any peculiarities or special behaviors of the 
function that your application should take into consideration 
in order to successfully call the function and efficiently use its 
results. 


Related Information References other sections or chapters in this or other manuals 
in the OS/2 LAN Requester/Server document set that may 
help you better understand or use the function. 
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Access Permission Category 


Description 


NetAccessAdd (admin, DOS)—See “NetAccessAdd” on page 3-6. 

NetAccessCheck (/ocal)—See “NetAccessCheck” on page 3-9. 

NetAccessDel (admin, DOS)—See “NetAccessDel” on page 3-12. 

NetAccessEnum (partially admin, DOS)—See “NetAccessEnum” on page 3-15. 
NetAccessGetInfo (partially admin, DOS)—See “NetAccessGetInfo” on page 3-18. 


NetAccessGetUserPerms (partially admin, DOS)—See “NetAccessGetUserPerms” on 
page 3-22. 


NetAccessSetInfo (admin, DOS)—See “NetAccessSetInfo” on page 3-25. 


The functions in the Access Permission category examine or modify user or group 
access permission records for server resources. They are used with the ACCESS.H 
and NETCONS.H include files. 


In order for a user to access a shared resource, an access permission record must be 
defined for that user. An access permission record defines how a user or group can 
access a shared resource. It contains a set of permissions for each user or group. 


Access permission records are created using the NetAccessAdd function. To delete 
all access permission records associated with a particular shared resource, call 
NetAccessDel. 


An access permission record contains: 
e The name of the resource 
e A list of users or groups permitted to use the resource 


e A list of access permissions granted to a particular user or group. 


The NetAccessGetInfo function can be called to return information on a particular 
access permission record. To obtain information on all access permission records for 
which the calling process has special permissions (ACCESS_PERM), call 
NetAccessEnum. 


The access permission record must be defined by a user or application that already 
has administrative permissions , or has special permission (ACCESS_PERM) for the 
resource being shared. Note that user permissions have precedence over group 
permissions. Ifa user is not defined in the access list for the shared resource, the 
user’s access permissions are the union of all groups to which the user belongs. For 
more information on access control checking, see the IBM Operating System/2 Local 
Area Network Server Version 1.2 Network Administrator's Guide. The 
NetAccessCheck function can be called to verify whether a user has permission to 
access a particular resource. If the user or group does not have access permission 
and access permission is needed, the access permission record can be changed from 
its original content with NetAccessSetInfo. 
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DOS Considerations 
Under DOS, these functions can be executed only on a remote server. 
Administrative privilege must have been granted to execute the functions. 


Attempting to execute the functions on a local requester returns 
NERR_RemoteOnly. 


Data Structures 
The level parameter controls the level of information provided to or returned from 
the NetAccessAdd, NetAccessEnum, NetAccessGetInfo, and NetAccessSetInfo 
functions. These functions use either a level 0 or a level 1 data structure. 


Access Permission Information (Level 0) 


struct access _info_0 { 
char far * accO_resource_name; 
}s 


where: 


° acc0_resource_name points to an ASCIIZ string containing the name of a 
resource type. acc0_resource_name uses the following formats: 


Resource Type Name Format 
Directory drive:pathname 

File drive:pathname 

Pipe \pipe\pipename 
Spooler queue \print\queuename 
Serial device queue \comm\chardevqueue 


Access Permission Information (Level 1) 


struct access_info_1 { 
char far * accl_resource_name; 


short accl_attr; 
short accl_count; 
}s 
where: 


¢ accl_resource_name points to an ASCIIZ string specifying the name of a 
particular resource (see preceding discussion on acc0_resource_name). 


¢ accl_attr specifies the attributes of accl_resource_name. The bits of accl_attr 
are defined as follows: 
Bit Meaning 


0 Audit all. When this bit is set, all access attempts will be audited. 
No other bits in the field can be set. It is an error to set any other 
bits when bit 0 is set. When bit 0 is cleared, the remaining bits are 
defined as described as follows in this table. 


1-3 Reserved with a value of 0. 


4 If 1, audit successful file opens. 


Chapter 3. API Function Descriptions 3-3 


Bit 


1] 
12-15 


Meaning 
If 1, audit successful file writes and successful directory creates. 


If 1, audit successful file deletes or truncates and successful 
directory deletes. 


If 1, audit successful file and directory ACL changes. 
If 1, audit failed file opens. 
If 1, audit failed file writes and failed directory creates. 


If 1, audit failed file deletes or truncates and failed directory 
deletes. 


If 1, audit failed file and directory ACL changes. 
Reserved with a value of 0. 
Notes: 


1. Other resources that can be accessed across the network, 
including spooler queues, serial device queues, and pipes, are 
audited using the FOR FILES bits. 


2. A value of 0 for the accl_attr word means that there is no 
auditing of resource accesses. A value of 1 means audit 
everything. Other values indicate the auditing of specific 
accesses. 


3. When write auditing is enabled, the “write audit” record will 
be generated when the file is successfully opened for write. 
written. Only one “write audit” record is produced per open 
instance of the file. If both write and open auditing are 
enabled, two audit records may be produced. 


4. File size changes (including truncation) are audited under the 
control of auditing bits 5 and 9. Thus, access that is 
controlled with the ACCESS WRITE permission bits is 
audited by way of auditing bits 5 and 9. 


5. Bit 3 is used in conjunction with bit 4 to allow the auditor to 
determine the duration of access. However, since this 
information is not required, the generation of the close audit is 
optional. 


¢ accl_count specifies the number of access_list data structures following the 
access_info_1 data structure. 


In addition, the access_info_1 data structure can be followed by zero or more (up to 
a maximum of 64) access_list data structures. These structures are used to define 
resource permissions for individual users or groups. 


Resource Permissions 


struct access list { 
char acl_ugname[UNLEN+1]; 
char acl_ugname_pad_1; 
short acl_access; 


}s 
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where: 


¢ acl_ugname is an ASCIIZ string specifying a particular user name or group 


name. 


¢ acl_ugname_pad_I WORD-aligns the data structure components. 


¢ acl_access specifies permission of a user name or a group name. acl_access is 
defined in ACCESS.H as follows: 


Manifest 


ACCESS_READ 


ACCESS_WRITE 
ACCESS_CREATE 


ACCESS EXEC 
ACCESS DELETE 
ACCESS ATRIB 


ACCESS PERM 


ACCESS_ALL 


ACCESS GROUP 


Related information 


Bit 
Mask 
0x01 
0x02 
0x04 


0x08 
0x10 
0x20 


0x40 


Ox7F 


0x8000 


Meaning 


Permission to read data from a resource, 
and by default execute the resource. 


Permission to write data to the resource. 


Permission to create an instance of the 
resource (such as a file); data can be 
written to the resource when creating it. 


Permission to execute the resource. 
Permission to delete the resource. 


Permission to modify the attributes of a 
resource (such as the date and time a file 
was last modified). 


Permission to modify the permissions 
(read, write, create, execute, and delete) 
assigned to a resource for a user or 
application. 


Permission to read, write, create, 
execute, or delete a resource, or to 
modify attributes or permissions. 


Permission for a particular group; if 
returned, indicates that the entry is for a 
group. 


For information on include files, see Appendix A, “Include Files.” 
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NetAccessAdd 


The NetAccessAdd (admin, DOS) function defines a user name or group name 
access permission record for a new resource. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetAccessAdd(servername, level, buf, buflen) 


char far * servername; 
short level; 
char far * buf ; 


unsigned short buflen; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ level specifies the level of detail (1) provided in the access_info_] data structure. 


¢ buf points to the access_info_1 data structure. The structure can be followed by 
zero or more access_list data structures. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_NETWORK_ACCESS_DENIED 65 Network access is 
denied. 
ERROR_BAD_NETPATH 53 The network path 
cannot be found. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA | 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_BufTooSmall 


NERR_OS2loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_ACFNotFound 


NERR_UserNotFound 


NERR_ResourceNotFound 


NERR_ResourceExists 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 


NERR_ACFFileIOFail 


Value 
2104 


2106 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2219 


2221 


2222 


2225 


2227 


2228 


2229 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The Net.ACC file is 
missing. 

The user name cannot 
be found. 


The netname cannot be 
found. 


The resource 
permission list already 
exists. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


An error was 
encountered in 
accessing the accounts 
database. 
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Manifest Value 
NERR_ACFTooManyLists 2230 


NERR _InvalidComputer 2351 


Meaning 


Too many lists were 
specified. 


The specified computer 
name is invalid. 


Other return codes may be returned from the following OS/2 functions: 


¢ DosAllocSeg 

¢ DosFreeSeg 

¢ DosFsCtl 

¢ DosFsCtlh(NETTRANSACTION) 

¢ DosFsCtlhINULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosFSRamSemClear 

¢ DosGetShrSet[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen 

¢ DosQFileMode 


e DosSemClear. 


Remarks 


To define the access permissions for a new resource, the contents of buf must include 
an access_info_1 data structure specifying the name of a resource, attributes, and the 
number of access_list data structures that are appended. Each access_list data 
structure specifies a user name or group name and associated permissions to be 


added to the access permission record of a resource. 


Related Information 
For information on: 


e Add functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 


¢ Deleting an access permission record—See “NetAccessDel” on page 3-12. 


e Listing server permissions and resources—See “NetAccessEnum” on page 3-15. 
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NetAccessCheck 


Syntax 


The NetAccessCheck (local) function verifies that a user name has the supplied 
permissions for a particular resource. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 


NetAccessCheck(reserved, uname, resource, operation, result) 


char far * 

char far * 

char far * 

unsigned short 
unsigned short far * 


where: 


e reserved is a NULL 


reserved; 
uname ; 
resource; 
operation; 
result; 


pointer. 


¢ uname points to an ASCIIZ string containing a user name. 


¢ resource points to an ASCIIZ string containing the local path name for the 
resource type, as follows: 


Type 
Directory 

File 

Pipe 

Spooler queue 


Serial device queue 


Format 
drive:pathname 
drive: pathname 
\pipe\pipename 
\print\queuename 


\comm\chardevqueue 


* operation specifies the type of access operation requested. Any combination of 
the following can be requested, as defined in ACCESS.H as follows: 


Manifest 
ACCESS_READ 
ACCESS_WRITE 


ACCESS CREATE 


ACCESS_EXEC 
ACCESS_DELETE 
ACCESS_ATRIB 


Bit 
Mask 
0x01 


0x02 
0x04 


0x08 
0x10 
0x20 


Meaning 


Permission to read data from a resource, 
and by default execute the resource. 


Permission to write data to the resource. 


Permission to create an instance of the 
resource (such as a file); data can be 
written to the resource when creating it. 


Permission to execute the resource. 
Permission to delete the resource. 


Permission to modify the attributes of a 
resource (such as the date and time a file 
was last modified). 


Chapter 3. API Function Descriptions 3-9 


Return Codes 


Manifest Bit 


Mask 
ACCESS _ PERM 0x40 
ACCESS_ALL 0x7F 


Meaning 


Permission to modify the permissions 
(read, write, create, execute, and delete) 
assigned to a resource for a user or 
application. 


Permission to read, write, create, 
execute, or delete a resource, or to 
modify attributes or permissions. 


result points to an unsigned short integer specifying whether or not the operation 
is permitted. result is only valid when the NetAccessCheck function returns the 
NERR Success return code. If result is 0, then the operation is permitted. 


Manifest 
NERR_ SUCCESS 
ERROR_ACCESS_DENIED 


ERROR_SEEK 
ERROR _NOT_ SUPPORTED 


ERROR_INVALID_ PARAMETER 
NERR ServerNotStarted 


NERR InternalError 
NERR_InvalidAPI 


NERR_ACFNotFound 
NERR_UserNotFound 
NERR_ACFFileIOFail 


NERR _InvalidDatabase 


Value 
0 
5 


pie 
50 


87 
2114 


2140 
2142 


2219 
2221 
2229 


2247 


Meaning 
No errors were encountered. 


Administrative privilege is 
required. 


The seek is invalid. 


This request is not supported by 
the network. 


The specified parameter is invalid. 


The Server service has not been 
started. 


An internal error has occurred. 


The requested API is not 
supported on the remote server. 


The Net.ACC file is missing. 
The user name cannot be found. 


An etror was encountered in 
accessing the accounts database. 


The UAS database file is 
corrupted. 


Other error return codes may be returned from the following functions: 


DosAllocSeg 
DosChgFilePtr 
DosFsCtl 
DosOpen 
DosRead. 
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Remarks 
If an access permission record cannot be found for the specified user name and the 
specified resource, the NetAccessCheck function tries to find the proper access 
permission record for the GUEST account, a special account set up for temporary 
users of the resource. GUEST accounts are defined in the IBMLAN.INI file. 


Related Information 
For information on: 


¢ Defining user or group access permissions—See “NetAccessAdd” on page 3-6. 


¢ Guest accounts—See the IBM Operating System/2 Local Area Network Server 
Version 1.2 Network Administrator's Guide. 


e Listing all permissions and resources—See See “NetAccessEnum” on page 3-15. 
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NetAccessDel 


Syntax 


Return Codes 


The NetAccessDel (admin, DOS) function deletes all access permission records for a 


particular shared resource. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetAccessDel (servername, resource) 


char far * servername; 
char far * resource; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


computer. 


¢ resource points to an ASCIIZ string containing the local path name for the 


resource type, as follows: 


Type 
Directory 


drive: pathname 


File 
Pipe 
Spooler queue 


Serial device queue 


Manifest 


0 No errors were 


NERR_SUCCESS 


ERROR_ACCESS_ DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_NETWORK_ACCESS_DENIED 


ERROR_INVALID_PARAMETER 
ERROR_INVALID_LEVEL 


ERROR_MORE DATA 
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Format 
drive: pathname 
\pipe\pipename 
\print\queuename 
\comm\chardevqueue 
Value Meaning 
encountered. 
5 Administrative 
privilege is required. 
8 Sufficient memory is 
not available. 
65 Network access is 
denied. 
87 The specified 
parameter is invalid. 
124 The Level parameter is 
invalid. 
234 Additional data is 


available, but the 
buffer is too small. 


Manifest 
NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_ACFNotFound 
NERR_ResourceNotFound 
NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_InvalidComputer 


Value 
2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2219 


2222 


Zeal 


2229 


2351 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The Net.ACC file is 
missing. 

The netname cannot be 
found. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFSRamSemClear 

¢ DosFreeSeg 

© DosFsCtl 

¢ DosFsCtlh(NETTRANSACTION) 
¢ DosFsCtlhINULLTRANSACT) 
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¢ DosFsctl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen 


e DosSemClear. 


Related Information 
For information on: 


¢ Defining user name or group name access permissions—See “NetAccessAdd” on 
page 3-6. 


¢ Del functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 


e Listing all permissions and resources—See See “NetAccessEnum” on page 3-15. 
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NetAccessEnum 


Syntax 


Return Codes 


The NetAccessEnum (partially admin, DOS) function enumerates all access 
permission records. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetAccessEnum(servername, basepath, recursive, level, 


buf, buflen, entriesread, totalentries) 


char far * servername; 
char far * basepath; 
short level; 
short recursive; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


basepath points to an ASCIIZ string containing a base path name for the shared 
resources. A NULL pointer or string means no basepath is to be used. 


recursive enables or disables recursive searching. If recursive is 0, 
NetAccessEnum returns entries only for the resource named as basepath. If 
recursive is non-zero, NetAccessEnum returns entries for all access control 
records whose resource matches basepath. 


level specifies the level of detail (0 or 1) requested for the returned access_info 
data structure. 


buf points to the returned access_info data structure. 
buflen specifies the size (in bytes) of the buf memory area. 


entriesread points to an unsigned short integer indicating the number of entries 
returned. 


totalentries points to an unsigned short integer indicating the number of entries 
available. 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS DENIED > Administrative 


privilege is required. 


ERROR _NOT_ENOUGH_MEMORY 8 Sufficient memory is 


not available. 
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Manifest 
ERROR _NETWORK_ACCESS DENIED 


ERROR INVALID PARAMETER 
ERROR INVALID LEVEL 


ERROR_MORE_ DATA 
NERR_NetNotStarted _ 


NERR_ShareMem 


NERR_RemoteOnly 
NERR OS2IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_ACFNotFound 
NERR_UserNotFound 
NERR_ResourceNotFound 
NERR_ACFNotLoaded 


NERR_ACFNoRoom 
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Value 
65 


87 


124 


234 


2102 


2104 


2106 


2134 


2138 


2139 


2140 


2141 


2219 


2221 


2222 


2227 


2228 


Meaning 


Network access is 
denied. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The Net.ACC file is 
missing. 

The user name cannot 
be found. 


The netname cannot be 
found. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


Manifest Value Meaning 


NERR_ACFFileIOFail 2229 An error was 
encountered in 
accessing the accounts 
database. 


NERR InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following functions: 

¢ DosAllocSeg 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsctl(KNETTRANSACTION) 

¢ DosFsctl(NULLTRANSACT) 

¢ DosFsctl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_ NOT_FOUND] 

¢ DosOpen 

¢ DosSemClear. 

Remarks 

The NetAccessEnum function can return entries for an application having only 
ACCESS_PERM permissions. If the user does not have administrative privileges, 
NetAccessEnum will not return ERROR_ACCESS_DENIED, but it will return 
NERR Success with zero entries. The basepath parameter limits the entries returned 
by NetAccessEnum. If basepath is a non-NULL string, basepath serves as a prefix 


for the path name. For example, if basepath is C:\PROG, NetAccessEnum returns 
access permission records for resources that begin with C:\PROG. 


The totalentries parameter indicates the number of entries available for the given 
basepath and recursive parameters, not the total number of entries in the access file. 


Therefore, NetAccessEnum returns information only for resources with non-default 
settings below the root directory specified in the request. Note that this is 
semantically consistent with a standard OS/2 LAN Requester/Server, which returns 
only explicit permissions. In addition, it is highly recommended that the recursive 
switch always be set to FALSE. 


Related Information 
For information on: 
e Adding an access permission record—See “NetAccessAdd” on page 3-6. 


e Enum functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 


¢ Retrieving information about a permissions of a resource—See 
“NetAccessGetInfo” on page 3-18. , 


e Verifying an access permission record of a resource—See “NetAccessCheck” on 
page 3-9. 
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NetAccessGetinfo 
The NetAccessGetInfo (partially admin, DOS) function retrieves information about 
the access permission record of a resource. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetAccessGetInfo(servername, resource, level, buf, 


buflen, totalavail) 


char far * servername; 
char far * resource; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far *  totalavail; 


where: 


servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


resource points to an ASCIIZ string containing the local path name for the 
resource type, as follows: 


Type Format 

Directory drive :pathname 

File drive:pathname 

Pipe \pipe\pipename 
Spooler queue \print\queuename 
Serial device queue \comm\chardevqueue 


level specifies the level of detail (0 or 1) requested for the returned access_info 
data structure. 


buf points to the returned access_info data structure. On a successful return, buf 
can contain an access_info_0 data structure or an access_info_1 data structure 
followed by zero or more access_list data structures. The number of access_list 
data structures returned can be found in the accl_count component of the 
access_info_1 data structure. 


buflen specifies the size (in bytes) of the buf memory area. 


totalavail points to an unsigned short integer indicating the number of bytes of 
information available. 
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Return Codes 


Manifest 
NERR_SUCCESS 


ERROR_NOT_ENOUGH_MEMORY 
ERROR_ACCESS_DENIED 
ERROR_NETWORK_ACCESS_DENIED 
ERROR_INVALID_PARAMETER 
ERROR_INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR WkstaNotStarted 


NERR _BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_ACFNotFound 


NERR_ResourceNotFound 


Value 


65 


87 


124 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2219 


2222 


Meaning 


No errors were 
encountered. 


Sufficient memory is 
not available. 


Administrative 
privilege is required. 


Network access is 
denied. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The Net.ACC file is 
missing. 


The netname cannot be 
found. 
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Remarks 


Manifest Value Meaning 


NERR_ACFNotLoaded 9007 The UAS database has 
not been started. 
NERR_ACFFileIOFail 2229 An error was 


encountered in 
accessing the accounts 
database. 


NERR_InvalidComputer 2351 The specified computer 
. name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsctl 

¢ DosFsctl(NETTRANSACTION) 

¢ DosFsctl(NULLTRANSACT) 

¢ DosFsctl(NetGetRdrAddr) 

* DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 

¢ DosOpen 


¢ DosSemClear. 


If the calling process does not have administrative privileges, NetAccessGetInfo can 
be successfully called only by a process that has special permissions 
(ACCESS_PERM) defined in the access permission record of the resource. 


The specified resource must be a complete path name. 


In specifying the gueuename for a resource, use the name originally assigned to the 
resource with the NetShareAdd function. 


If level is 1, NetAccessGetInfo returns an access_info_] data structure followed by an 
access list data structure for each entry in the list of the resource. The number of 
entries can be determined by examining the acc/_count component in the 

access _info_1 data structure. 


If buf cannot hold all of the fixed-length and variable-length data (all access_list data 
structures), NetAccessGetInfo returns the NERR_BufTooSmall error code, and not 
the ERROR_MORE_DATA error code as most GetInfo functions do when there is 
more data available. 


The proper way to determine the size of buf is to first call NetAccessGetInfo with 
level as 1 and buflen as 0. In this case, NetAccessGetInfo will return the number of 
bytes required in totalavail. After obtaining this value, call NetAccessGetInfo with 
level as 1, and specify the new buflen. 
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Related Information 
For information on: 


¢ GetInfo functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 
e Listing all resources and permissions—See “NetAccessEnum” on page 3-15. 


¢ Modifying the current permissions for a resource—See “NetAccessSetInfo” on 
page 3-25. 
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NetAccessGetUserPerms 
The NetAccessGetUserPerms (partially admin, DOS) function supplies a specified 
user’s or group’s permission to a resource. The resource can be a file, directory, 
drive or logical resource and can be specified remotely by a universal naming 
convention (UNC) path as well as by a server name. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetAccessGetUserPerms(servername, usergroupname, resource, permission) 


char far * servername; 
char far * usergroupname; 
char far * resource; 
short far * permission; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ usergroupname points to an ASCIIZ string containing the name of the user or 
group to be inquired. 


¢ resource points to an ASCIIZ string containing the path name for the resource 
type which can be a directory, file, or drive, as follows: 


Type Format 

Directory drive:pathname 

File drive: pathname 

Pipe \pipe\pipename 
Spooler queue \print\queuename 
Serial device queue \comm\chardevqueue 


¢ permission points to a field where the permission bit field is to be returned. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_BAD_NETPATH 53 The network path 


cannot be found. 
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Manifest 
ERROR_NETWORK_ACCESS DENIED 


ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE_DATA 


NERR_NetNotStarted 


NERR_ ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_ACFNotFound 


NERR_UserNotFound 


NERR_ResourceNotFound 


NERR_ACFNotLoaded 


Value 
65 


87 


124 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2219 


2221 


2222 


Zany 


Meaning 


Network access is 
denied. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The Net.ACC file is 
missing. 


The user name cannot 
be found. 


The netname cannot be 
found. 


The UAS database has 
not been started. 
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Manifest Value 


NERR_ACFFileIOFail 2229 
NERR _InvalidDatabase 2247 
NERR_InvalidComputer 2351 


Meaning 


An error was 
encountered in 
accessing the accounts 
database. 


The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsctl 

¢ DosFsctl(NETTRANSACTION) 
¢ DosFsctlh(NULLTRANSACT) 
¢ DosFsctl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen 

e DosRead 


¢ DosSemClear. 


Remarks 


The resource can be specified remotely by a UNC path as well as by a server name. 
The permissions returned are based on the user’s entry and the entry for any groups 
to which the user belongs. Priority is always given to the user’s entry if one exists. 


This API requires administrative privilege with the exception that users are always 
allowed to request their own permissions to any resource. In addition, a user with 
“P” permission to the resource can get the permissions for any user or group. 
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NetAccessSetinfo 


Syntax 


The NetAccessSetInfo (admin, DOS) function changes an access permission record 
for a resource. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetAccessSetInfo(servername, resource, level, 
buf, buflen, parmnum) 


char far * servername; 
char far * resource; 
short level; 

char far * buf; 
unsigned short buflen; 
short parmnums; 
where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


® resource points to an ASCIIZ string containing the local path name for one of 
the following resource types: 


Type Format 

Directory drive:pathname 

File drive: pathname 

Pipe \pipe\pipename 
Spooler queue \print\queuename 
Serial device queue \comm\chardevqueue 


e level specifies the level of detail (1) provided in the access_info_1 data structure. 


e buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


e buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum specifies whether a specific component of the access_info_1 data 
structure is being set, or the entire data structure. If parmnum is zero, buf must 
contain an access_info_] data structure followed by zero or more access_list data 
structures. If parmnum is non-zero, only the acc]_attr component in the 
access_info_1 data structure is set, and parmnum must pass the ordinal position 
value (ACCESS_ATTR_PARMNUM) of the acc/_attr component. 
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Return Codes 


Manifest 
NERR_SUCCESS 


ERROR_ACCESS_DENIED 


ERROR_NOT_ENOUGH_ MEMORY 


ERROR_SEEK 
ERROR_BAD_NETPATH 


ERROR_NETWORK_ACCESS_DENIED 


ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 
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Value 


25 
53 


65 


87 


124 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


The seek is invalid. 


The network path 
cannot be found. 


Network access is 
denied. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


Manifest Value Meaning 


NERR_ACFNotFound 2219 The Net.ACC file is 
missing. 

NERR_UserNotFound 2221 The user name cannot 
be found. 

NERR _ ResourceNotFound 2222 The netname cannot be 
found. 

NERR_ACFNotLoaded 2227 The UAS database has 
not been started. 

NERR_ACFNoRoom 2228 There are too many 


names in the access 
control file. 


NERR_ACFFileIOFail 2229 An error was 
encountered in 
accessing the accounts 


database. 
NERR_ACFTooManyLists 2230 Too many lists were 
specified. 
NERR_InvalidDatabase 2247 The UAS database file 
is corrupted. 
NERR_InvalidComputer 2351 The specified computer 
name is invalid. 
NERR_CanNotGrowUASFile 2456 It is not possible to 


grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

e DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsctl 

¢ DosFsctl((NETTRANSACTION) 

¢ DosFsctl(NULLTRANSACT) 

¢ DosFsctl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize[-ERROR_DISK_FULL] 

¢ DosOpen 
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¢ DosQFileInfo 

¢ DosRead 

e DosSemClear 

¢ DosWrite. 
Remarks 


The specified resource must be a complete path name. For example, file or directory 
resources must include a drive letter. 


A user or application that has ACCESS PERM permissions for a particular resource 
can change the access permission record for that resource and remove its permissions 
for that resource. 


The parmnum is used only to change the accl_attr field in the access_info_1 data 
structure. To change the user or group permissions through this API, call 
NetAccessGetInfo first. Otherwise, if the user or group list is not complete, the 
information that is not included will be lost. 


Related Information 
For information on: 


e Listing server resources and permissions—See “NetAccessEnum” on page 3-15. 
e Retrieving permissions of a resource—See “NetAccessGetInfo” on page 3-18. 


¢ SetInfo functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 
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Alert Category 


Description 


NetAlertRaise (/ocal)—See “NetAlertRaise” on page 3-34. 
NetAlertStart (Jocal)—See “NetAlertStart” on page 3-37. 
NetAlertStop (/ocal)—See “NetAlertStop” on page 3-40. 


The functions in the Alert category provide a system for notifying network service 
programs and applications of network events. They are used with the ALERT.H 
and NETCONS.H include files. 


An event is a particular instance of a process or state of hardware defined by an 
application or by the OS/2 LAN Requester/Server software. The OS/2 LAN 
Requester/Server sends out an alert, in the form of a message or the resetting of a 
semaphore, when certain events occur. Other programs, network services, or internal 
network components use the NetAlertRaise function to raise an alert, notifying 
various applications or users when a particular type of event occurs. 


The ALERT.H include file defines the following classes of events for the alerts that 
are sent out: 


e A print job has completed. 

e A user or application received a broadcast message. 
e An entry was added to an error log file. 

e A network event required administrative assistance. 


e A user accessed or used certain applications or resources. 


Other classes of alerts can be defined for network applications as needed. For 
example, if an application routinely writes large amounts of data to a disk drive, 
running the risk of filling the disk, the user might want the event of no free disk 
space to trigger an alert that notifies the application to pause or end the process 
slowing the system. 


An application or network service, known as a client, registers to be notified of an 
event (or class of events) by calling the NetAlertStart function. Each registration 
adds an entry to an alert table. 


A client can receive alert messages through one of two delivery mechanisms: 
¢ A mailslot (registered as \mailslot\name) 


e A system semaphore (registered as \sem\name). If a program requires detailed 
information about an event, it should be registered as a mailslot, since a 
semaphore cannot transmit such information. 


A client can be registered for one type of event or for several types by calling the 
NetAlertStart function a number of times. 


To discontinue alerts for a registered client, use the NetAlertStop function to remove 
that entry of a client in the alert table for the particular class of event. 
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Data Structures 


Header Structure 


Event Structures 


To change the internal size of the alert table (thus allowing more alerts to be 
defined), a user or application must modify the numalert component in the 
IBMLAN.INI file, and then restart the requester (by using the NET STOP RDR /y 
and NET START RDR commands). 


An application registered as a mailslot client receives information about each class of 
event for which it is registered. This information consists of a fixed-length header 
followed by variable-length information specific to the type of event, as defined in 
the ALERT.H include file. 


The fixed-length header contains the following data: 


/* Standard event data structure */ 


struct std_alert { 
long alrt_timestamp; 
char alrt_eventname[ELVLEN+1]; 
char alrt_pad1; 
char alrt_servicename[SNLEN+1] ; 
}; 
where: 
¢ alrt_timestamp indicates the time and date of the event. 
e alrt_eventname is an ASCIIZ string indicating the alert class (type of event). 
e alrt_padl WORD-aligns data structure components. 


¢ alrt_servicename is an ASCIIZ string indicating the application that is raising the 
alert. 


The ALERT.H include file contains data structures for predefined alert classes. 
These structures define only the fixed-length part of the information, not the ASCIIZ 
strings that follow some of the structures. Each of the six structures is described in 
the following sections. 
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Print Request Completed 


struct print_other_info { 
short alrtpr_jobid; 
short alrtpr_status; 
long alrtpr_submitted; 
long alrtpr_size; 
, 
/* followed by consecutive ASCIIZ strings 


char computername[] ; 
char username[]; 
char queuename[] ; 
char destname[]; 
char status_string[]; 


*/ 
where: 
¢ alrtpr_jobid is the identification number of the print job. 
¢ alrtpr_status indicates the status of the print job. 
¢ alrtpr_submitted is a time stamp indicating when the print job was submitted. 
¢ alrtpr_size indicates the size (in bytes) of the print job. 


* computername is an ASCIIZ string indicating the requester or server that 
submitted the print job. 


¢ username is an ASCIIZ string indicating the user that requested the printing. 

¢ queuename is an ASCIIZ string indicating the queue that handled the print job. 
e destname is an ASCIIZ string indicating the printer that handled the job. 

¢ status_string is information that the print processor returns. This string 


corresponds to status_string in the printjob data structure for the print job. 


Network Message Received: In this case, no data structure is defined; however, the 
text from the received message is in the following format: 


char msg _text []; 
where: 


¢ msg_text is an ASCIIZ string of message text. 


Entry Made to Error Log File 


struct errlog_other_info { 
short alrter_errcode; 
long alrter_offset; 


ie 
where: 


¢ alrter_errcode is the error code that was logged. 


¢ alrter_offset is the offset for the new entry in the error log file. 
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Notify Administrator of Network Event 


struct admin_other_info { 
short alrtad_errcode; 
short alrtad_numstrings; 


}s 
/* followed by 0-9 consecutive ASCIIZ strings 


char mergestrings [][]; 
*/ 


where: 
e alrtad_errcode is the error code for the new message in the message log file. 


¢ alrtad_numstrings indicates the number (0 through 9) of consecutive ASCIIZ 
strings that mergestrings contains. 


¢ mergestrings is a series of consecutive ASCIIZ strings that comprise the error 


message indicated by alrtad_errcode. 


Notify User of an Event 


struct user_other_info { 
short alrtus_errcode; 
short alrtus_numstrings; 


}; 
/* followed by the consecutive ASCIIZ strings 


char mergestrings [][]; 
char username[]; 
char computername[]; 


*/ 


where: 
e alrtus_errcode is the error code for the new message in the message log file. 


¢ alrtus_numstrings indicates the number (0 through 9) of consecutive ASCIIZ 
strings that mergestrings contains. 


© mergestrings is a series of consecutive ASCIIZ strings that comprise the error 
message indicated by alrtus_errcode. 


© username is the user name of the user or application that is being affected by the 
alert. 


© computername is the name of the computer that the user or application is 
accessing. . 
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Related Information 


The ALERT.H include file contains macros to simplify access to the variable-length 


fields in the alert structure as follows: 


Macro 


ALERT_OTHER_INFO, 
ALERT OTHER INFO F 


ALERT VAR DATA, 
ALERT VAR DATA F 


For information on: 


Task 


When given a pointer to the start of the 
std_alert data structure, the 
ALERT_OTHER INFO macro resolves 
to a pointer to the variable-length part 
of the alert message (the information 
specific to the alert class). Use 
ALERT_OTHER_INFO_F when a far 
pointer is required. 


Works with the data structures defined 
in ALERT.H. Given a pointer to the 
beginning address of the data structure, 
ALERT_VAR_DATA returns a pointer 
to the first variable-length ASCIIZ 
string. Use ALERT _VAR_DATA F 
when a far pointer is required. 


e Include files—See Appendix A, “Include Files.” 


¢ Creating mailslots—See “Mailslot Category” on page 3-146. 
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NetAlertRaise 


The NetAlertRaise (local) function notifies all clients registered in the alert table that 
a particular event has occurred. 


Syntax 


#include <netcons.h> 
#include <alert.h> 


unsigned far pascal 

NetAlertRaise(event, buf, buflen, timeout) 
const char far * event; 

const char far * buf; 

unsigned short  buflen; 

unsigned long timeout ; 


where: 


¢ event points to an ASCIIZ string indicating the type of alert to raise. The 
ALERT.H include file defines the following classes of alerts: 


Manifest ASCIIZ String Meaning 

ALERT_ADMIN_EVENT “ADMIN” Notify an 
administrator. 

ALERT_ERRORLOG EVENT “ERRORLOG” Entry added to 
error log file. 

ALERT_MESSAGE_ EVENT “MESSAGE” User or 
application 
received a 
message. 

ALERT _PRINT_EVENT “PRINTING” Print job 
completed or 

. print error. 
ALERT_USER_EVENT “USER” Application or 


resource used. 


Other classes of events can be defined as necessary. 
¢ buf points to the std_alert data structure followed by additional alert data. 
e buflen specifies the size (in bytes) of the buf memory area. 


© timeout specifies the number of milliseconds to wait for event information to be 
written to the mailslot. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 


not available. 
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Manifest 
ERROR _INVALID_PARAMETER 


ERROR_INVALID NAME 


ERROR_INVALID_LEVEL 


ERROR_MORE_DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmail 


NERR_OS82IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_InvalidComputer 


NERR_NoSuchAlert 


Value 


123 


124 


234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2351 


2432 


Meaning 


The specified 
parameter is invalid. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested APT is 
not supported on the 
remote server. 


The specified computer 
name is invalid. 


The Alerter service has 
not been started. 


Chapter 3. API Function Descriptions 3-35 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFSRamSem Request 

DosFreeSeg 

DosFsctl(NETTRANSACTION) 
DosFsctlh(NULLTRANSACT) 
DosFsctl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosSemClear 


DosSemRequest. 


NetAlertRaise notifies all clients registered as semaphores or mailslots when a 
particular system event takes place. Semaphores are cleared, and mailslots are sent 
messages. 


For mailslot clients, NetAlertRaise writes information from buf to clients registered 
as mailslots by calling the DosWriteMailslot function. 


All semaphore clients must be created with the NoExclusive option set and must be 
called by a process that calls the DosMuxSemWait function on the semaphore. This 
procedure informs the process of the state transition of the semaphore. 


Related Information 


For information on: 


Creating a mailslot—See “DosMakeMailslot” on page 3-150. 
Registering a client for an event—See “NetAlertStart” on page 3-37. 


Ending event watching—See “NetAlertStop” on page 3-40. 
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NetAlertStart 


The NetAlertStart (local) function registers a client to be notified of a particular type 
of network event. 


Syntax 


#include <netcons.h> 
#include <alert.h> 


unsigned far pascal 

NetAlertStart (event, recipient, maxdata) 
const char far * event; 

const char far * recipient; 

unsigned short maxdata; 


where: 


¢ event points to an ASCIIZ string indicating the type of event of which the client 
is to be notified. The ALERT.H include file defines the following classes of 


alerts: 
Manifest ASCIIZ String Meaning 
ALERT_ADMIN_EVENT “ADMIN” Notify an 
administrator. 
ALERT ERRORLOG EVENT “ERRORLOG” Entry added to 
error log file. 
ALERT MESSAGE _ EVENT “MESSAGE” User or 
application 
received a 
message. 
ALERT _PRINT_EVENT “PRINTING” Print job 
completed or 
print error. 
ALERT_USER_EVENT “USER” Application or 


resource used. 


Other classes of events can be defined as necessary. 


e recipient points to an ASCIIZ string specifying the mailslot or semaphore client 
to receive the alerts. 


¢ maxdata specifies a limit (in bytes) to the information the mailslot client will 
receive about events in that class. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 


not available. 
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Manifest 
ERROR_INVALID_ PARAMETER 


ERROR_INVALID_NAME 


ERROR_INVALID_LEVEL 


ERROR_MORE_DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR InvalidAPI 


NERR_BadEventName 
NERR_InvalidComputer 


NERR AlertExists 


NERR_TooManyAlerts 
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Value 
87 


123 


124 


234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2143 


2351 


2430 


2431 


Meaning 


The specified 
parameter is invalid. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The event name is 
incorrectly formed. 


The specified computer 
name is invalid. 


The specified client is 
already registered for 
the specified event. 


The Alerter service 
table is full. 


Remarks 


Related Information 


Manifest Value Meaning 


NERR_BadRecipient 2433 The Alerter service 
recipient is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFSRamSemRequest 
¢ DosFreeSeg 
¢ DosFsctlh(NETTRANSACTION) 
¢ DosFsctl(NULLTRANSACT) 
¢ DosFsctl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear 


¢ DosSemRequest. 


Event names are ASCIIZ strings stored in ALERT.H. Applications can define their 
own events, specifying the name when calling the NetAlertStart and NetAlertRaise 
functions. If you create an event data structure, be sure to choose a name that does 
not duplicate a name used by another application. 


If recipient is a semaphore, calling NetAlertRaise for the specified event opens, 
clears, resets, and closes the system semaphore. The process owning the semaphore 
must have created it with the NoExclusive option set; presumably such a process will 
be executing a DosSemWait or DosMuxSemWait function on the semaphore and 
will have the transition status of the semaphore. 


Note that if NetAlertStart starts a particular alert, the alert will still exist (even when 
a process is ended) until the NetAlertStop function is called to stop the alert. 


For information on: 
¢ Creating a mailslot—See “DosMakeMailslot” on page 3-150. 


e Creating a semaphore—See DosCreateSem in the IBM Operating System/2 
Technical Reference Version 1.2 Programming Reference, Volume 1. 


¢ Reading a mailslot—See “DosReadMailslot” on page 3-152. 


e¢ Ending the watch of a client for a class or type of event—See “NetAlertStop” on 
page 3-40. 
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NetAlertStop 


The NetAlertStop (local) function removes a registered client from the alert table. 
Syntax 


#include <netcons.h> 
#include <alert.h> 


unsigned far pascal 
NetAlertStop(event, recipient) 
const char far * event; 

const char far * recipient; 


where: 


¢ event points to an ASCIIZ string specifying the class of alerts from which the 
registered client is to be excluded. The ALERT.H include file defines the 
following classes of alerts: 


Manifest ASCIIZ String Meaning 
ALERT_ADMIN_EVENT “ADMIN” Notify an 
administrator. 
ALERT_ERRORLOG EVENT “ERRORLOG” Entry added to 
error log file. 
ALERT_MESSAGE_ EVENT “MESSAGE” User or 
application 
received a 
message. 
ALERT_PRINT_EVENT “PRINTING” Print job 
completed or 
print error. 
ALERT_USER_EVENT “USER” Application or 


resource used. 


Other classes of events can be defined as necessary. 


¢ recipient points to an ASCIIZ string containing the user name of the client 
whose registration is to be canceled. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
. privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR MORE DATA 


NERR _NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR _InvalidComputer 


NERR_NoSuchAlert 


Value 
234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2351 


2432 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The specified computer 
name is invalid. 


The Alerter service has 
not been started. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFSRamSemRequest 


¢ DosFreeSeg 


¢ DosFsctlh(NETTRANSACTION) 
¢ DosFsctl(NULLTRANSACT) 
¢ DosFsctl(NetGetRdrAddr) 


¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


e DosSemClear 


e¢ DosSemRequest. 
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Related Information 
For information on registering a client to watch for a particular event, see 
“NetAlertStart” on page 3-37. 
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Auditing Category 


Description 


NetAuditClear (admin, DOS)—See “NetAuditClear” on page 3-58. 
NetAuditRead (admin, DOS)—See “NetAuditRead” on page 3-61. 
NetAuditWrite (/ocal, server)—See “NetAuditWrite” on page 3-66. 


The functions in the Auditing category control the audit log file, which contains an 
audit trail of operations that occur on a server. They are used with the AUDIT.H 
and NETCONS.H include files. 


Each time a user or application connects to or disconnects from resources on a 
server, an audit entry can be generated to record the connection or disconnection. 
Audit entries are stored in an ASCII file. The default audit log file is 
\IBMLAN\LOGS\NET.AUD. All of the auditing functions perform their 
operations on this file. 


Note: The auditing functions only control changing the contents of the audit log 
file. To read the audit log file, an application must first call the 
NetAuditRead function to obtain the handle of the file. The DosRead 
function can then be called to read the file. To close the file, an application 
must call the DosClose function. 


OS/2 LAN Requester/Server provides for the following types of audit entries: 
e A change in a status of a server 
e The beginning of a session 
¢ The end of a session 
e A password error 
e The start of a connection 
e A disconnection 
e A rejected connection request 
e An access made to a resource 
e¢ The rejection of an access 
¢ The closing of a file, device, or pipe 
¢ The change of service status code or text 
e A modification of access control profile 
¢ A modification of the UAS database 
e¢ The logon of a user 
¢ The logoff of a user 
¢ The denial of a logon 


e The limit of account exceeded. 
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Applications can create additional types of audit entries with the NetAuditWrite 
function. . 


The other two auditing functions open (NetAuditRead) and clear (NetAuditClear) 
the audit log file. 


Data Structures 
All audit entries include a fixed-length header used in conjunction with 
variable-length data specific to the type of entry. Because of the variable lengths 
and structures of the ae_data portion of the audit entry (it is possible for ae_data to 
be 0 bytes in length), only the fixed header is defined in the audit_entry data 
structure. 


The variable-length portion of the audit entry can also contain an offset to a 
variable-length ASCIIZ string. The offset values are unsigned short integers. To 
determine the value of the pointer to this string, add the offset value to the address 
of the ae_data structure. 


The following example illustrates this procedure. Assume that ap points to a buffer 
containing a complete audit entry and that ae_type contains the value AE_CONNSTOP, 
specifying the predefined ae_connstop data structure. To make the variable 
computer_name point to the ASCIIZ string containing the name of the client whose 
connection was stopped, an application. would perform the following algorithm: 


struct audit_entry * ap; /* fixed portion of audit entry */ 
struct ae_connstop * acp; /* variable-length structure */ 
char * computer_name; /* pointer to variable-length 
string */ 
/* calculate offset to variable-length struct */ 
acp = (struct ae_connstop *) ((char *) ap + ap-> ae_data_offset); 


/* calculate offset to computer name */ 


computer_name = (char *) acp + acp -> ae_cp_compname; 
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The Fixed-Length Header 


The format of the fixed portion of the audit entry is as follows: 


struct audit_entry { 
unsigned short ae_len; 
unsigned short ae_reserved; 
unsigned long ae_time; 
unsigned short ae_type; 
---- unsigned short ae_data_offset; /* offset from 
| beginning address of 
| audit_entry */ 
| }s 
| 
| /* variable-length data specific to type of audit entry 
| 


-> char ae_data[]; 


unsigned short ae_len2; 


*/ 
where: 
¢ ae_len and ae_len2 specify the length of the audit entry. (Note that ae_len is 
included both at the beginning and the end of the audit entry to enable both 
backward and forward scanning of the file.) To calculate the entry size, add the 


size of the audit_entry data structure to the size of the variable-length ae_data 
and the size of an unsigned short integer, as follow: 


totalsize = sizeof (struct audit_entry) + 
sizeof (ae_data) + sizeof (unsigned short); 


© ae_reserved is 0. 
© ae_time is a time stamp indicating the time the audit file log entry was made. 


© ae_type indicates the type of audit entry. Type values ranging from 0x0000 
through 0x07FF are reserved. The NETCONS.H include file defines the 
following types of data entries: 


Manifest Value Purpose 
AE_SRVSTATUS 0 Status of server changed. 
AE_SESSLOGON 1 Session logged on. 
AE_SESSLOGOFF Zz Session logged off. 
AE_SESSPWERR 3 Password error. 
AE_CONNSTART 4 Connection started. 
AE_CONNSTOP 5 Connection stopped. 
AE_CONNREJ 6 Connection rejected. 
AE_RESACCESS2 7 Access granted. 
AE_RESACCESSREJ 8 Access rejected. 

AE _CLOSEFILE 9 File, device, or pipe closed. 
AE_ SERVICESTAT 1] Service status code or text 


changed. 
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Manifest Value Purpose 


AE_ACLMOD 12 Access control list modified. 

AE UASMOD 13 User account subsystems 
database modified. 

AE _NETLOGON 14 User logged on to the network. 

AE NETLOGOFF 15 User logged off of the network. 

AE NETLOGDENIED 16 Network logon denied. 

AE ACCLIMITEXCD 17 Account limit exceeded. 


¢ ae_data_offset specifies the byte offset from the beginning of the audit entry to 
the start of the variable-length portion (ae_data) of the audit entry. To calculate 


the start of ae_data, add the value of ae_data_offset to the starting address of the 
fixed-length portion of the entry. 


¢ ae_data is the variable-length portion of the audit entry, which differs depending 
on the type of entry specified by ae_type. The information starts at 
ae_data_offset bytes from the top of the audit entry. See the following section 
for information on the structure of each entry type that the OS/2 LAN 
Requester/Server software defines. 


ae_data Structures 
The following data structures, specific to the ten types of audit entries, are defined in 
the AUDIT.H include file. The structures follow (though not necessarily 
immediately) the audit_entry header. 


Server Status Changes 


struct ae_srvstatus { 
unsigned short ae_sv_status; 
}s 


where: 


* ae_sv_status is one of four values indicating a status of the server. These values, 
defined in AUDIT.H, mean the following: 


Manifest Value Meaning 
AE_SRVSTART 0 Server software started. 
AE_SRVPAUSED 1 Server software paused. 
AE_SRVCONT 2 Server software restarted. 
AE_ SRVSTOP 3 Server software stopped. 


Session Begins 


struct ae_sesslogon { 
unsigned short ae_so_compname; /* offset */ 
unsigned short ae_so username; /* offset */ 
unsigned short ae_so_privilege; 


}3 
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where: 


¢ ae_so_compname is an offset (from the beginning address of the ae_sesslogon 
data structure) to an ASCIIZ string indicating which requester established the 
session. 


* ae_so_username is an Offset (from the beginning address of the ae_sesslogon data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_so_username and ae_so_compname are the same. 


¢ ae_so_privilege is one of three values specifying the permission level assigned to 
ae_so_username. These values, defined in AUDIT.H, have the following 


meanings: 

Manifest Value Privilege 
AE_GUEST 0 Guest 
AE_USER 1 User 
AE_ADMIN Z Admin 
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Session Ends 


struct ae_sesslogoff { 
unsigned short ae_sf_compname; /* offset */ 
unsigned short ae_sf_username; /* offset */ 
unsigned short ae_sf_reason; 

}; 


where: 


© ae_sf_compname is an offset (from the beginning address of the ae_sesslogoff 
data structure) to an ASCIIZ string indicating the requester that established the 
session. 


¢ ae_sf_username is an offset (from the beginning address of the ae_sesslogoff data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_sf username and ae_sf compname are the same. 


¢ ae_sf_reason is one of five values indicating why the session was disconnected. 
These values, defined in AUDIT.H, mean the following: 


Manifest Value Meaning 

AE_ NORMAL 0 Normal disconnection or user 
name limit. 

AE_ ERROR 1 Error, session disconnect, or bad 
password. 

AE _AUTODIS 2 Auto-disconnect (time out), 


share removed, or administrative 
permissions required. 


AE_ADMINDIS 3 Administrative disconnection 
(forced). 
AE_ACCRESTRICT 4 Forced off by account system 


due to account restriction, such 
as logon hours. 


Password Error 


struct ae_sesspwerr { 
unsigned short ae_sp_compname; /* offset */ 
unsigned short ae_sp_username; /* offset */ 
}s 


where: 


* ae_sp_compname is an offset (from the beginning of the ae_sesspwerr data 
structure) to an ASCIIZ string indicating the requester that established the 
session. 


* ae_sp_username is an offset (from the beginning of the ae_sesspwerr data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_sp_username and ae_sp_compname are the same. 
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Connection Started 


struct ae_connstart { 
unsigned short ae_ct_compname; /* offset */ 
unsigned short ae_ct_username; /* offset */ 
unsigned short ae_ct_netname; /* offset */ 
unsigned short ae_ct_connid; 

}s 


where: 


¢ ae_ct_compname is an offset (from the beginning address of the ae_connstart 
data structure) to an ASCIIZ string indicating the requester that established the 
session. 


¢ ae_ct_username is an offset (from the beginning address of the ae_connstart data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_ct_username and ae_ct_compname are the same. 


¢ ae_ct_netname is an offset (from the beginning address of the ae_connstart data 
structure) to an ASCIIZ string indicating the netname of the resource with which 
the connection was made. 


¢ ae_ct_connid is the connection identification number. 


Connection Stopped 


struct ae_connstop { 
unsigned short ae_cp_compname; /* offset */ 
unsigned short ae_cp_username; /* offset */ 
unsigned short ae_cp_netname; /* offset */ 
unsigned short ae_cp_connid; 
unsinged short ae_cp_reason; 

}; 


where: 


* ae_cp_compname is an offset (from the beginning address of the ae_connstop data 
structure) to an ASCIIZ string indicating the requester that established the 
session. 


* ae_cp_username is an offset (from the beginning address of the ae_connstop data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_cp_username and ae_cp_compname are the same. 


© ae_cp_netname is an offset (from the beginning address of the ae_connstop data 
structure) to an ASCIIZ string indicating the connected netname of the resource. 
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¢ ae_cp_connid is the connection identification number. 


® ae_cp_reason is one of three values indicating why the session was disconnected. 
These values, defined in AUDIT.H, mean the following: 


Manifest 
AE NORMAL 


AE_SESSDIS 


AE UNSHARE 


Connection Rejected 


struct ae_connrej { 
unsigned short ae_cr_compname; 
unsigned short ae_cr_username; 
unsigned short ae_cr_netname; 
unsigned short ae_cr_reason; 


ie 


where: 


Value 
0 


/* offset */ 
/* offset */ 
/* offset */ 


Meaning 


Normal disconnection, or user 
name limit. 


Error, session disconnect, or bad 
password. 


Autodisconnect (timeout), share 
removed, or administrative 
permissions lacking. 


* ae_cr_compname is an offset (from the beginning address of the ae_connrej data 
structure) to an ASCIIZ string indicating the requester that established the 


session. 


* ae_cr_username is an Offset (from the beginning address of the ae_connrej data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_cr_username and ae_cr_compname are the same. 


* ae_cr_netname is an offset (from the beginning address of the ae_connrej data 
structure) to an ASCIIZ string indicating the desired netname of a resource. 


* ae_cr_reason is one of four values indicating why the session was disconnected. 
These values are defined in AUDIT.H, as follows: 


Manifest 
AE USERLIMIT 


AE BADPW 


AE_ADMINPRIVREQD 


AE_NOACCESSPERM 
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Value 
0 


Meaning 


Normal disconnection, or user 
name limit. 


Error, session disconnect, or bad 
password. 


Autodisconnect (timeout), share 
removed, or administrative 
permissions lacking. 


No access permissions to shared 
resource. 


Access Granted 


struct ae_resaccess { 


}3 


unsigned short ae_ra2_compname; /* offset */ 
unsigned short ae_ra2_username; /* offset */ 
unsigned short ae_ra2_resname; /* offset */ 
unsigned short ae_ra2_operation; 

unsigned short ae_ra2_returncode; 

unsigned short ae_ra2_restype; 

unsigned short ae_ra2_fileid; 


where: 


© ae_ra2_compname is an offset (from the beginning address of the ae_resaccess 


data structure) to an ASCIIZ string indicating the requester that established the 
session. 


ae_ra2_username is an offset (from the beginning address of the ae_resaccess 
data structure) to an ASCIIZ string indicating the name of the user who 
initiated the session. If 0, ae_ra_username and ae_ra_compname are the same. 


ae_ra2_resname is an offset (from the beginning address of the ae_resaccess data 
structure) to an ASCIIZ string indicating the name of the resource accessed. 


ae_ra2_operation is one of seven values indicating which operation was 
performed. These values, defined in ACCESS.H, mean the following: 


Manifest Bit Meaning 
Mask 
ACCESS_READ 0x01 Data was read or executed from 
a resource. 
ACCESS_WRITE 0x02 Data was written to a resource. 
ACCESS_CREATE 0x04 An instance of the resource 


(such as a file) was created; data 
may have been written to the 
resource when creating it. 


ACCESS_EXEC 0x08 A resource was executed. 

ACCESS DELETE 0x10 A resource was deleted. 

ACCESS_ATRIB 0x20 Attributes of a resource were 
modified. 

ACCESS PERM 0x40 Permissions (read, write, create, 


execute, and delete) of a 
resource for a user or 
application were modified. 


ae_ra_returncode gives the return code from the particular operation. If 0, the 
operation was successful. 


© ae_ra_restype gives the server message block (SMB) request function code. 


¢ ae_ra_fileid gives the server identification number of a file. 
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Access Rejected 


struct ae_resaccessrej { 
unsigned short ae_rr_compname; /* offset */ 
unsigned short ae_rr_username; /* offset */ 
‘unsigned short ae_rr_resname; /* offset */ 
unsigned short ae_rr_operation; 

}; 


where: 


® ae_rr_compname is an offset (from the beginning address of the ae_resaccessrej 
data structure) to an ASCIIZ string indicating the requester that established the 
session. 


© ae_rr_username is an offset (from the beginning address of the ae_resaccessrej 
data structure) to an ASCIIZ string indicating the name of the user who 
initiated the session. If 0, ae_rr_username and ae_rr_compname are the same. 


¢ ae_rr_resname is an offset (from the beginning address of the ae_resaccessrej 
data structure) to an ASCIIZ string indicating the name of the resource to which 
access was denied. 


¢ ae_rr_operation is one of seven values indicating the operation requested. These 
values are defined in ACCESS.H, as follows: 


Manifest Bit Meaning 
Mask 
ACCESS_READ 0x01 Data was read or executed from 
a resource. 
ACCESS_WRITE 0x02 Data was written to a resource. 
ACCESS _CREATE 0x04 An instance of the resource 


(such as a file) was created; data 
may have been written to the 
resource when creating it. 


ACCESS_EXEC 0x08 A resource was executed. 

ACCESS_DELETE 0x10 A resource was deleted. 

ACCESS_ATRIB 0x20 Attributes of a resource were 
modified. 

ACCESS PERM 0x40 Permissions (read, write, create, 


execute, and delete) of a 
resource for a user or 
application were modified. 


Service Status Code or Text Changed: The audit log entry will be written when 
service-status auditing is on, and a service performs a NetServiceStatus call that 
updates the service status (svcs_status). Only changes of status to one of the 
following values cause an audit entry to be written: 


¢ INSTALLED 
¢ UNINSTALLED 
¢ PAUSED 
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CONTINUED (ACTIVE). 


struct ae_servicestat { 


ys 


unsigned short ae_ss_compname; /* offset */ 
unsigned short ae_ss_username; /* offset */ 
unsigned short ae_ss_ svcname; /* offset */ 
unsigned short ae_ss_ status; 

unsigned long ae_ss_code; 

unsigned short ae_ss_text; /* offset */ 
unsigned short ae_ss_returnval; 


where: 


ae_ss_compname is an offset (from the beginning address of the ae_servicestat 
data structure) to an ASCIIZ string indicating the requester that established the 
session. 


ae_ss_username is an offset (from the beginning address of the ae_servicestat data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_ss_username and ae_ss_compname are the same. 


ae_ss_svcname is an offset (from the beginning address of the ae_servicestat data 
structure) to an ASCIIZ string indicating the name of a service. 


ae_ss_status is the service status being set. 
ae_ss_code is the service code being set. 
ae_ss_text is an offset to text being set. 


ae_ss_returnval is the return value. 


Access Control List Modification: The audit log entry will be written when an 
existing access control list (ACL) record is modified or deleted. 


struct ae_aclmod { 


hs 


unsigned short ae_am_compname; /* offset */ 
unsigned short ae_am_username; /* offset */ 
unsigned short ae_am_resname; /* offset */ 
unsigned short ae_am_action; 
unsigned long ae_am_datalen; 


where: 


ae_am_compname is an offset (from the beginning address of the ae_aclmod data 
structure) to an ASCIIZ string indicating the requester that established the 
session. 


ae_am_username is an offset (from the beginning address of the ae_aclmod data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_am_username and ae_am_compname are the same. 


ae_am_resname is an offset (from the beginning address of the ae_aclmod data 
structure) to an ASCIIZ string that indicates the name of a resource that owns 
the accessed files. 


ae_am_action is the action performed on the ACL record, as follows: 
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Value Meaning 


0 Modification 
1 Delete 
2 Add 


¢ ae_am_datalen is the length of data following the fixed data structure. This is 
always zero in records generated by the OS/2 LAN Requester/Server. 


User Account Subsystem Modification: The audit log entry will be written when an 
existing user accounts subsystem (UAS) record is modified or deleted, or the UAS 
modals are modified. 


struct ae_uasmod { 
unsigned short ae_um_compname; /* offset */ 
unsigned short ae_um_username; /* offset */ 
unsigned short ae_um_resname; /* offset */ 
unsigned short ae_um_rectype; 
unsigned short ae_um action; 
unsigned long ae_um datalen; 

}; 


where: 


* ae_um_compname is an offset (from the beginning address of the ae_uasmod data 
structure) to an ASCIIZ string indicating the requester that established the 
session. 


* ae_um_username is an offset (from the beginning address of the ae_uasmod data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_um_username and ae_um_compname are the same. 


* ae_um_resname is an offset (from the beginning address of the ae_uasmod data 
structure) to an ASCIIZ string indicating the name of a resource that owns the 
accessed files. 


* ae_um_rectype is the type of UAS record, as follows: 


Value Meaning 

0 User record. 

1 Group record. 
Z VAS modals. 


¢ ae_um_action is the action performed on the UAS record, as follows: 


Value Meaning 
0 Modification 
1 Deletion 
2 Addition 


¢ ae_um_datalen is the length of data following the fixed data structure. This is 
always zero in records generated by the OS/2 LAN Requester/Server. 
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Network Logon Record: This record is written by the server that processes the 
network logon of the user. 


struct ae_netlogon { 
unsigned short ae_no_compname; /* offset */ 
unsigned short ae_no_username; /* offset */ 
unsigned short ae_no_privilege; 
unsigned short ae_no_authflags; 

}s 


where: 


¢ ae_no_compname is an offset (from the beginning address of the ae_netlogon data 
structure) to an ASCIIZ string indicating the requester that established the 
session. 


* ae_no_username is an offset (from the beginning address of the ae_netlogon data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_no_username and ae_no_compname are the same. 


¢ ae_no_privilege is the privilege of the user logging on, as follows: 


Manifest Value 
AE_GUEST 0 
AE_USER 1 
AE_ADMIN 2 


¢ ae_no_authflags is a reserved field. 


Network Logoff Record: This record is written by the server that processes the 
network logoff of the user. 


struct ae_netlogoff { 
unsigned short ae_nf_compname; /* offset */ 
unsigned short ae_nf_username; /* offset */ 
unsigned short ae_nf_reason; 
unsigned short ae_nf_subreason; 

}; 


where: 


¢ ae_nf_compname is an offset (from the beginning address of the ae_netlogoff data 
structure) to an ASCIIZ string indicating the requester that established the 
session. 


° ae_nf_username is an offset (from the beginning address of the ae_netlogoff data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_nf_username and ae_nf_compname are the same. 


° ae_nf_reason is the reason for logoff, as follows: 


Manifest Value Meaning 
AE NORMAL 0 Normal logoff by user. 
AE_ERROR 1 Disconnect due to error. 
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Manifest Value Meaning 


AE_AUTODIS 2 Auto-disconnect (station down). 
AE_ADMINDIS 3 Administrator disconnected user. 
AE_ACCRESTRICT 4 Forced off by account system 


due to account restriction, such 
as logon hours. 


¢ ae_nf_subreason is the details of reason for logoff. When nf_reason is 
AE_ACCRESTRICT, one of the following is true: 


Manifest Value Meaning 
AE_LIM_UNKNOWN 0 Unknown or unavailable. 
AE_LIM_LOGONHOURS 1 Logon hours. 
AE_LIM_EXPIRED Z Account expired. 


Otherwise, this value is zero. 


Network Logon Denied: The audit log entry is written when the network logon 
request is denied. 


struct ae_netlogdenied { 
unsigned short ae_nd_compname; /* offset */ 
unsigned short ae_nd_username; /* offset */ 
unsigned short ae_nd_reason; 
unsigned short ae_nd_subreason; 

}; 


where: 


¢ ae_nd_compname is an offset (from the beginning address of the ae_netlogdenied 
data structure) to an ASCIIZ string indicating the requester that established the 
session. 


¢ ae_nd_username is an offset (from the beginning address of the ae_netlogdenied 
data structure) to an ASCIIZ string indicating the name of the user who 
initiated the session. If 0, ae_nd_username and ae_nd_compname are the same. 


¢ ae_nd_reason is the reason for denial of log on, as follows: 


Manifest Value Meaning 

AE_GENERAL 0 General access denied. 

AE BADPW | Incorrect password. 
AE_ACCRESTRICT 4 Forced off by account system 


due to account restriction, such 
as logon hours. 
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Related Information 


¢ ae_nd_subreason is the details of reason for denial. When nd_reason is 
AE _ACCRESTRICT, one of the following is true: 


Manifest Value 
AE_ LIM UNKNOWN 0 
AE_LIM_LOGONHOURS l 


AE_LIM EXPIRED 
AE _LIM_INVAL_WKSTA 
AE LIM_DISABLED 


- WwW WY 


Otherwise, this value is zero. 


Meaning 

Unknown or unavailable. 
Logon hours. 

Account expired. 
Requester ID not valid. 
Account disabled. 


Account Limit Exceeded: The audit log entry is written when users remain logged 
on while their account limitations no longer permit them to be logged on. 


struct ae_acclim { 


unsigned short ae_al_compname; /* offset */ 
unsigned short ae_al_username; /* offset */ 
unsigned short ae_al_resname; /* offset */ 


unsigned short ae_al_limit; 
}; 


where: 


¢ ae_al_compname is an offset (from the beginning address of the ae_acclim data 
structure) to an ASCIIZ string indicating the requester that established the 


session. 


¢ ae_al_username is an offset (from the beginning address of the ae_acclim data 
structure) to an ASCIIZ string indicating the name of the user who initiated the 
session. If 0, ae_al_username and ae_al_compname are the same. 


¢ ae_al_resname is the offset to the resource name. 


¢ ae_al limit is the limit that was exceeded, as follows: 


Manifest Value 
AE_LIM_ UNKNOWN 0 
AE_LIM_LOGONHOURS 1 
AE_LIM_EXPIRED 2 


For information on: 


Meaning 
Unknown or unavailable. 
Logon hours. 


Account expired. 


e OS/2 LAN Requester/Server network commands and IBMLAN.INI file—See the 
IBM Operating System/2 Local Area Network Server Version 1.2 Network 


Administrator's Guide. 


¢ Permission levels—See “User Category” on page 3-382 and “Access Permission 


Category” on page 3-2. 
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NetAuditClear 
The NetAuditClear (admin, DOS) function clears (and optionally saves) the audit 
log file of a server. 


Syntax 


#include <netcons.h> 
#include <audit.h> 


unsigned far pascal 

NetAuditClear(servername, backupfile, reserved) 
const char far * servername; 

const char far * backupfile; 

char far * reserved; 


where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


e backupfile points to an ASCIIZ string assigning a name for an optional backup 
file. The calling application must have Write privileges for the path specified by 
backupfile. The path name must also be accessible by the OS/2 DosMove 
function. If the path name is relative, it is assumed relative to the 
IBMLAN\LOGS directory. 


A NULL pointer tells NetAuditClear not to save the audit log entries. 
¢ reserved must be NULL. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR _PATH_NOT_FOUND 3 The path was not 
found. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_NETWORK_ACCESS_DENIED 65 Network access is 
denied. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_NAME 123 There is an incorrect 


character or incorrectly 
formed file system 
name. 
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Manifest 
ERROR_INVALID_ LEVEL 


ERROR_FILENAME EXCED RANGE 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_ RemoteOnly 


NERR_BufTooSmalil 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_InvalidComputer 


NERR_CantType 


Value 
124 


206 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2351 


2391 


Meaning 


The Level parameter is 
invalid. 


The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The specified computer 
name is invalid. 


The type of input 
cannot be determined. 
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Remarks 


Related Information 


Other error return codes may be returned from the following OS/2 functions: 


DosDelete 

DosFsRamSemClear 

DosFreeSeg 

DosFsCtl 
DosFsCtl(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosFsCtlNet.GetRdrAddrQ) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosMove 

DosOpen 

DosSemClear 


redir.GetInitPath. 


NetAuditClear clears the audit log file of all entries and optionally saves the contents 
to another file. 


The NetAuditWrite function (see “NetAuditWrite” on page 3-66) issues an admin 
alert when the audit log file reaches 80% capacity and again when the file reaches 
100% capacity. At 100%, NetAuditWrite fails. Therefore, applications should 
periodically clear the audit log file of outdated information. 


To set a maximum size for the audit log file, use one of the following methods: 


Use the NET CONFIG command with the /MAXAUDITLOG option (see the 
IBM Operating System/2 Local Area Network Server Version 1.2 Network 
Administrator's Guide for more information). 


Set the maxauditlog parameter in the IBMLAN_INI file (see the JBM Operating 
System/2 Local Area Network Server Version 1.2 Network Administrator's Guide 
for a description of IBMLAN.IND. 


Call the NetServerSetInfo function with the sv_maxauditsz parameter. 


For information on: 


Getting the status of audit log file capacity—See “NetAlertRaise” on page 3-34. 
Writing an entry to the audit log file—See “NetAuditWrite” on page 3-66. 
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NetAuditRead 


Syntax 


The NetAuditRead (admin, DOS) function opens and returns an OS/2 file handle to 
the audit log file of a server. 


#include <netcons.h> 
#include <audit.h> 


unsigned far pascal 


NetAuditRead (servername, reservedl, ploghnd], offset, reserved2, 
reserved3, flags, buf, buflen, bytesread, bytesavail) 


const char far * servername; 
const char far * reserved] 
HLOG far * ploghnd1; 
unsigned long offset; 
unsigned short far * reserved2; 
unsigned long reserved3; 
unsigned long flags; 
char far * buf; 
unsigned short buflen; 
unsigned short far * bytesread; 


unsigned short far * 


where: 


bytesavail; 


servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


reservedI must be NULL. 
ploghndl is the pointer to the returned log handle. 


offset is the record offset to begin read. The offset is ignored unless flags bit 1 is 
set. If this bit is set, offset is taken as a zero-based offset based on record 
number, not bytes, at which the data returned should begin. Note that the 
record offset parameter is zero based from both directions, dependent upon the 
direction of the read. If reading backwards is specified, then the Oth record is 
the last record in the file. If reading forward, then the Oth record is the first 
record in the file. 


reserved2 must be NULL. 

reserved3 must be zero. 

flags specifies the open flags, bitmapped as shown here. 
buf is the pointer to the buffer for returned data. 

buflen specifies the size (in bytes) of the buf memory area. 


bytesread points to an unsigned short integer indicating the number of bytes that 
were read into the buffer. 


bytesavail points to an unsigned short integer indicating the number of bytes that 
were available. 
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The bitmapped flags fields are as follows: 


Bits Meaning 


0 If 0, the file is read normally. If 1, the file is read backwards and 
records are returned in the buffer in reverse-chron order (newest 
records first). 


1 If 0, read proceeds normally and sequentially. If 1, read proceeds from 
the Nth record from the start of the file. “N” is the offset parameter. 
2-31 Reserved; must be 0. 


The offset is ignored unless flags bit 1 is set. If this bit is set, offset is taken as a 
zero-based offset based on record number, not bytes, at which the data returned 
should begin. 


An application calling NetAuditRead for the first time must initialize the 128-bit log 
handle as follows: 


Bits Value 
127(MSB)-64 0 
63-0(LSB) 1 


Where the LSB is the last (rightmost) bit. Thereafter, each call to NetAuditRead 
must be given the value for the log handle that was returned by the previous call to 
NetAuditRead. 


Notes: 


1. If bytesread is 0 and bytesavail is not 0, the buffer is too small to hold the next 
record in the file. 


2. Unlike other uses of bytesavail, in this case, the value may be OxFFFF, which is 
shorthand for “OxFFFF or more.” There can potentially be much more than 
64KB data available. The application should continue to process entries until 
this value is returned to 0. 


The data is returned in the buffer. The application should use the bytesread value to 
determine the end of valid data in the buffer. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SHARING_ VIOLATION 32 A sharing violation 
occurred. 
ERROR_BAD_NETPATH 53 The network path 


cannot be found. 
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Manifest 
ERROR _NETWORK_ ACCESS DENIED 


ERROR_INVALID_PARAMETER 
ERROR_NET_WRITE_FAULT 


ERROR_OPEN_FAILED 


ERROR_INVALID_NAME 


ERROR INVALID_LEVEL 


ERROR_FILENAME_EXCED_RANGE 


ERROR_MORE DATA 


NERR _NetNotStarted 


NERR _ ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


Value 
65 


87 


88 


110 


123 


124 


206 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


Meaning 


Network access is 
denied. 


The specified 
parameter is invalid. 


A network data fault 
has occurred. 


The open/created 
failed due to explicit 
fail command. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 
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Manifest Value Meaning 


NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_InvalidComputer 2351 The specified computer 
name is invalid. 

NERR_CantType 2357 The type of input 
cannot be determined. 

NERR_LogFileChanged 2378 This log file has 
changed between reads. 

NERR_LogFileCorrupt 2379 This log file is corrupt. 

NERR_InvalidLogSeek 2440 The log file does not 


contain the requested 
record number. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosChgFilePtr 
¢ DosCLose 
¢ DosDevIOCtl 
¢ DosFSRamSemClear 
¢ DosFreeSeg 
¢ DosFsCtlh(NETTRANSACTION) 
¢ DosFsCthNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen 
¢ DosRead 
¢ DosSemClear 
¢ redir.GetInitPath. 

Remarks 
After NetAuditRead returns the handle of the audit log file, an application must call 


the DosRead function to read the contents of the file. To close the file, an 
application calls the DosClose function. 
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Related Information 
For information on: 


e Clearing an audit log file—See “NetAuditClear” on page 3-58. 


¢ Closing an audit log file—See DosClose in JBM Operating System/2 Technical 
Reference Version 1.2 Programming Reference, Volume 1. 


¢ Reading an audit log file—See DosRead in IBM Operating System/2 Technical 
Reference Version 1.2 Programming Reference, Volume 1. 


¢ Writing an entry to the audit log file—See “NetAuditWrite” on page 3-66. 
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NetAuditWrite 


Syntax 


Return Codes 


The NetAuditWrite (local, server) function writes an audit trail entry to the local 


audit log file. 


#include <netcons.h> 
#include <audit.h> 


unsigned far pascal 


NetAuditWrite(type, buf, buflen, reservedl, reserved2) 


unsigned short type; 
const char far * buf; 


unsigned short buflen; 
char far * reserved]; 
char far * reserved2; 
where: 


© type specifies the type of entry to write to the file. 


¢ buf points to the variable data of the data structure. 


e buflen specifies the size (in bytes) of the buf memory area. 


e reserved! and reserved2 are NULL pointers to reserved ASCIIZ strings. 


Manifest 


NERR_SUCCESS 

ERROR_ACCESS_ DENIED 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_SHARING_VIOLATION 


ERROR_NOT_SUPPORTED 


ERROR_BAD_NETPATH 
ERROR_NETWORK_ACCESS DENIED 
ERROR_INVALID PARAMETER 
ERROR_NET_WRITE_FAULT 


ERROR_CP8N_FAILED 
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Value 


0 


32 


50 


53 


65 


87 


88 


110 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


A sharing violation 
occurred. 


This request is not 
supported by the 
network. 


The network path 
cannot be found. 


Network access is 
denied. 


The specified 
parameter is invalid. 


A network data fault 
has occurred. 


The open/created 
failed due to explicit 
fail command. 


Manifest 
NERR_NetNotStarted 


NERR ServerNotStarted 


NERR_WkstaNotStarted 


NERR_LogOverflow 


Remarks 


Value 


2102 


2114 


2138 


2377 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


The Server service has 
not been started. 


The Requester service 
has not been started. 


This log file exceeds 
the maximum defined 
size. 


NetAuditWrite issues an admin alert by calling the NetAlertRaise function when the 
audit log file reaches 80% capacity and again when the file reaches 100% capacity. 
At 100% audit log capacity, the NetAuditWrite function fails, returning the error 


code NERR_LogOverflow. 


To return successfully, the NetAuditWrite function requires that the auditing entry 
in the IBMLAN_INI file be set to YES, as follows: 


auditing = yes 


Related Information 
For information on: 


e Closing the audit log file—See DosClose in IBM Operating System/2 Technical 


Reference Version 1.2 Programming Reference, Volume 1. 


e Retrieving size of the audit log file—See “NetServerGetInfo” on page 3-292. 


e Setting the maximum size of the audit log file—See “NetServerSetInfo” on 


page 3-295. 
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Configuration Category 


Description 


NetConfigGet2 (admin, DOS)—See “NetConfigGet2” on page 3-70. 
NetConfigGetAll2 (admin, DOS)—See “NetConfigGetAll2” on page 3-73. 


The functions in the Configuration category retrieve network configuration 
information from the IBMLAN.INI file. The NetConfigGet2 function retrieves a 
single parameter value for a given network component; NetConfigGetAll2 returns all 
of the parameters for the given component. These functions are used with the 
CONFIG.H and NETCONS.H include files. 


The IBMLAN.INI file is an ASCII file containing the configuration information for 
OS/2 LAN Requester/Server services. User-defined services and applications also 
store network configuration information in this file. 


The IBMLAN.INI file consists of component lines, parameter lines, and comment 
lines, in a format that enables the Configuration functions to easily browse through 
and retrieve the information. The format is as follows: 


¢ Component lines mark the start of information on a component, in the form: 
[componentname | 

e Parameter lines contain a parameter and a value, in the form: 
parameter = value 


The parameter value can consist of arbitrary text and is not processed by the 
Configuration functions, except that leading and trailing spaces are stripped. 
Interpretation of the value is left to the caller. No quotation marks are allowed 
as part of the parameter value. 


For any one component, if a parameter appears several times, NetConfigGetAll2 
returns each occurrence; NetConfigGet2 returns only the first instance. The 
same parameter name can be used under different components without affecting 
the NetConfigGet2 return. 


¢ Comment lines are any blank lines or lines in which the first nonblank character 
is a semicolon (;). 


An IBMLAN._INI requester component might contain the following information: 


[requester ] 
; define net_tool requester 
computername = net_tool 
charcount = 16 


As shown, requester defines a computer name of net_tool and specifies that 16 
bytes of characters must accumulate before a requester sends them to a serial 
device queue. 
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Note: The IBMLAN.INI file contains default values for network components. 
These values may not reflect actual values passed to a network service. If 
you notice inconsistencies between IBMLAN.INI entries and actual service 
values, examine the manner in which you have defined these service values 
within your application. To maintain consistency, it is a good idea to call 
NetConfigGetAll2 and examine the returned values before setting new 
parameter values for a given component. 


DOS Considerations 
These APIs cannot be called locally on a DOS requester to retrieve information from 
the DOSLAN.INI file. However, these APIs can be called remotely on a DOS 
requester to retrieve information from the IBMLAN.INI file. 


Related Information 
For information: 


e The IBMLAN.INI file—see the JBM Operating System/2 Local Area Network 
Server Version 1.2 Network Administrator's Guide. 


e The DOSLAN INI file—see the JBM OS/2 DOS LAN Requester User's Guide. 
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NetConfigGet2 


The NetConfigGet2 (admin, DOS) function retrieves a specified parameter value 
from the IBMLAN.INI file of a local computer or a remote server. 


Syntax 


#include <netcons.h> 
#include <config.h> 


unsigned far pascal 
NetConfigGet2(servername, reserved, component, parameter, 


buf, buflen, parmlen) 


char far * servername; 
char far * reserved; 
char far * component; 
char far * parameter 3 
char far * buf; 
unsigned short buflen; 


unsigned short far * parmlen; 


where: 


Return Codes 


servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
computer. 


reserved must be NULL. 


component points to an ASCIIZ string specifying the name of the component to 
be searched. 


parameter points to an ASCIIZ string specifying the parameter whose value is to 
be returned. 


buf points to the memory address where the value of a parameter is to be 
returned. 


buflen specifies the size (in bytes) of the buf memory area. 


parmlen points to an unsigned short integer indicating the size (in bytes) of a 
parameter. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_FILE_NOT_FOUND 2 The file was not found. 
ERROR_PATH_NOT_FOUND 3 The path was not 
found. 
ERROR ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR _NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SHARING VIOLATION 32 A sharing violation 
occurred. 
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Manifest 
ERROR INVALID PARAMETER 


ERROR_INVALID_ LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR _WkstaNotStarted 


NERR _BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_CfgCompNotFound 


NERR_CfgParamNotFound 


Value 


124 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2146 


2147 


Meaning 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The program could not 
find the specified 
component in the 
IBMLAN.INI file. 


The program could not 
find the specified 
parameter in the 
IBMLAN.INI file. 
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Remarks 


Other error return codes may be returned from the following OS/2 functions: 


DosChgFilePtr 

DosDuphandle 

DosFsRamSemClear 

DosFreeSeg 
DosFsCtlh(NETTRANSACTION) 
DosFsCtlh. NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg 
DosOpen[-ERROR_OPEN_FAILED] 
DosRead 


DosSemClear. 


NetConfigGet2 returns the value (ASCIIZ string) for a single parameter of a 
specified component in buf. This string is the entire value content of the 
IBMLAN.INI line for the specified parameter, which is all text to the right of the 
equal sign (=). Leading and trailing spaces are stripped from this text. No other 
processing is performed on it. 
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NetConfigGetAll2 


Syntax 


Return Codes 


The NetConfigGetAll2 (admin, DOS) function retrieves all configuration 
information for a given network component in the IBMLAN.INI file of a local 
computer or a remote server. 


#include <netcons.h> 
#include <config.h> 


unsigned far pascal 
NetConfigGetAl12(servername, reserved, component, buf, buflen, 
bytesread, bytesavail) 


char far * servername; 
char far * reserved; 
char far * component; 
char far * buf ; 
unsigned short buflen; 


unsigned short far * bytesread; 
unsigned short far * bytesavail; 


where: 


* servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
computer. 


e reserved must be NULL. 


* component points to an ASCIIZ string specifying the name of the component to 
search. 


¢ buf points to the memory address where the parameter values of a component 
are to be returned. 


e buflen specifies the size (in bytes) of the buf memory area. 


e bytesread points to an unsigned short integer indicating the number of bytes 
returned to buf. 


e bytesavail points to an unsigned short integer indicating the number of bytes of 
data that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_FILE_NOT_FOUND Z The file was not found. 
ERROR PATH NOT_FOUND 3 The path was not 
found. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR SHARING VIOLATION 32 A sharing violation 
occurred. 
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Manifest 
ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE_ DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_CfgCompNotFound 


NERR_LineTooLong 


NERR_JobNotFound 
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Value 


124 


234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2146 


2149 


2151 


Meaning 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The program could not 
find the specified 
component in the 
IBMLAN.INI file. 


A line in the 
IBMLAN.INI file is 
too long. 


The print job does not 
exist. 


Other error return codes may be returned from the following OS/2 functions: 


DOS Considerations 
This API can be called remotely on a DOS requester to retrieve information from 
the IBMLAN.INI file. 


Remarks 


DosChgFilePtr 

DosDuphandle 

DosFsRamSemClear 

DosFreeSeg 
DosFsCtl(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg 
DosOpen[-ERROR_OPEN_FAILED] 
DosRead 


DosSemClear. 


NetConfigGetAll2 returns in buf a set of concatenated ASCIIZ strings, representing 
configuration information for the specified component. Each string is ended by a 
NULL byte (ASCII 0), and the whole buffer is ended by a NULL string. 
Information is returned in the form parm=value. The parameter name (left of the = 
sign) is in uppercase. bytesread and bytesavail are filled in as for GetInfo calls. 


For example, 


foo = Bar,1,long comment string " 


in the IBMLAN_INI file is returned as: 


"FOO=Bar,1,long comment string" 
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Connection Category 


Description 


Data Structures 


NetConnectionEnum (admin, server, DOS)—See “NetConnectionEnum” on 
page 3-78. 


The NetConnectionEnum function lists all connections made to a server by a 
requester client or all connections made to a shared resource of a server. The 
function is used with the SHARES.H and NETCONS.H include files. 


A requester accesses a shared resource of a server by means of a connection. Thus, 
a connection is the path between a redirected local device name of a requester and a 
shared resource of a server. Using a NetUseAdd (UNC) name can establish a 
connection without any local device name. 


The NetConnectionEnum function returns data at a detail level of 0 or 1, using the 
following data structures: 


Connection Information (Level 0) 


struct connection_info_0 { 
unsigned short coniQ_id; 


}; 


where: 


¢ coni0_id is the connection identification number. 


Connection Information (Level 1) 


struct connection_info_1 { 
unsigned short conil_id; 
unsigned short conil_type; 
unsigned short conil_num_opens; 
unsigned short conil_num_users; 
unsigned long conil_time; 


char far * conil_username; 
char far * conil_netname; 
}s 
where: 


¢ conil_id is the connection identification number. 


¢ conil_type indicates the type of connection made from the local device name to 
the shared resource. The SHARES.H include file defines the following types of 


connection: 

Manifest Value Meaning 
STYPE_DISKTREE 0 Disk connection. 
STYPE_PRINTQ I Spooler queue connection. 
STYPE_DEVICE 2 Serial device connection. 
STYPE_IPC 3 Interprocess communication 


(IPC) connection. 
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© conil_num_opens indicates the number of files that are currently open as a result 
of the connection. 


¢ conil_num_users indicates the number of users on the connection. 
¢ conil_time indicates the number of seconds the connection has been established. 


© conil_username points to an ASCIIZ string indicating the user that made the 
connection. 


¢ conil_netname points to an ASCIIZ string indicating either the netname of the 
shared resource of the server or the computer name of the requester, depending 
on which name was specified as the qualifier parameter of the 
NetConnectionEnum function. The type of name supplied to conil_netname is 
the inverse of the type supplied to the qualifier parameter. 


Related Information 


For information on connecting a device name of a requester to a shared resource of 
a server, see “NetUseAdd” on page 3-372. 
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NetConnectionEnum 
The NetConnectionEnum (admin, server, DOS) function gives a listing of 
connections made to a shared resource of a server, or of all connections established 
from a particular computer to a server. 


Syntax 


#include <netcons.h> 
#include <shares.h> 


unsigned far pascal 
NetConnectionEnum(servername, qualifier, level, buf, 
buflen, entriesread, totalentries) 


const char far * servername; 
const char far * qualifier; 
short level; 
char far * buf ; 
unsigned short buflens; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
server. 


¢ qualifier points to an ASCIIZ string specifying either the netname of the shared 
resource whose connections will be listed or the client name of the requester 
whose connections to the shared resource will be listed (qualifier cannot be a 
NULL pointer or string). 


¢ level specifies the level of detail (0 or 1) for the returned connection_info data. 
¢ buf points to the connection_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an integer indicating the number of entries that were 
returned to buf. 


¢ totalentries points to an integer indicating the number of entries that were 


available. 
Return Codes 

Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS DENIED 5 Administrative privilege is 
required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is not 
available. 

ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 

ERROR_NETWORK_ACCESS_ DENIED — 65 Network access is denied. 
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Manifest 
ERROR_INVALID_ PARAMETER 


ERROR_INVALID_LEVEL 


ERROR. MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_OSZ2loctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_NetNameNotFound 


NERR_ClientNameNotFound 


NERR _InvalidComputer 


Value 
87 


124 


234 


2102 


2104 


2106 


2114 


2134 


2138 


2139 


2140 


2141 


2142 


2310 


2312 


2351 


Meaning 


The specified parameter is 
invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the buffer 
is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has not 
been started. 


An internal error 
occurred when calling the 
workstation driver. 


The Requester service has 
not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is not 
supported on the remote 
server. 


This shared resource does 
not exist. 


A session does not exist 
with that computer name. 


The specified computer 
name is invalid. 
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Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 

DosFsCth. NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


If qualifier specifies a requester, NetConnectionEnum returns a list of all connections 
made between the requester and the specified server during the current session. 


When qualifier specifies a shared resource, NetConnectionEnum returns a list of all 
connections made to the shared resource. 


Related Information 


For information on: 


Listing all available servers—See “NetServerEnum2” on page 3-289. 


Listing sessions on a server—See “NetSessionEnum” on page 3-331. 
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Domain Category 
NetGetDCName (DOS)—See “NetGetDCName” on page 3-82. 


NetLogonEnum (partially admin, DOS)—See “NetLogonEnum” on page 3-85. 


The functions in the Domain category deal specifically with the information of a 
domain and are exclusive of other categories. They are used with the ACCESS.H 
and NETCONS.H include files. 


Description 
The functions in this category deal with domain-specific information. The 
NetGetDCName function obtains the name of the domain controller when provided 
the name of the domain. The NetLogonEnum function enumerates the information 
of logged-on users in a domain. The information is in the level 0, 1, or 2 
user_logon_info data structures. See the data structure information under “User 
Category” on page 3-382. 
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NetGetDCName 


Given a domain name, the NetGetDCName (DOS) function returns the name of the 
domain controller if there is any. The NULL domain name is taken to mean obtain 
the domain controller (DC) of the primary domain. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGetDCName(servername, domain, buf, buflen) 


char far * servername; 
char far * domain; 
char far * buf; 


unsigned short buflen; 
where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ domain points to an ASCIIZ string containing the name of the domain. 
¢ buf points to the buffer for the name of the domain controller to be returned. 


¢ buflen specifies the size (in bytes) of the buffer buf 


Return Codes 


Manifest . Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR _INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_NAME 123 There is an incorrect 


character or incorrectly 
formed file system 


name. 

ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 

ERROR_MORE_ DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 


NERR_DCNotFound 


Value 
2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2351 


2453 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


No domain controller 
was found on this 
domain. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosAllocSeg 
¢ DosDeleteMailslot 
¢ DosFsRamSemClear 


¢ DosFreeSeg 


¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCth(KNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 


¢ DosGetShrSeg 


¢ DosMakeMailslot[-ERROR_ALREADY_EXISTS] 


¢ DosSemClear. 
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Remarks 
If the return code is 0 (success), the buffer contains an ASCIIZ string representing 
the name of the domain controller as a UNC name, for example, “\\server.” 


Because NetGetDCName attempts to find the domain controller for the specified 
domain each time it is called, this function may affect the performance of 
applications that call it often. However, since the domain controller of a domain 
may change, applications should not cache the domain controller name for more 
than a small set of operations. It is recommended that the application be written 
without more than very local caching, unless performance tests indicate that calls to 
NetGetDCName are the specific cause of poor performance. 


Even then, the application should take care to refresh its internal cache by calling 
this function when possible. 
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NetLogonEnum 


Syntax 


Return Codes 


The NetLogonEnum (DOS) function supplies information about logged-on users. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetLogonEnum(servername, level, buf, 
buflen, entriesread, totalentries) 


char far * servername; 
short level; 

char far * buf; 

unsigned short buf lens; 
unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


e level specifies the level (0 or 2) of detail supplied to the data structure. 
¢ buf points to the user_logon_info data structures. 

¢ buflen specifies the size (in bytes) of the user_logon_info data structure. 
¢ entriesread contains the number of entries on return. 


e totalentries contains the total entries available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 2) Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest Value Meaning 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 


NERR_ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 

NERR_OSZIoctiError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR InvalidAPI 2142 The requested API is 


not supported on the 
remote server. 


NERR_ACFNotFound 2219 The Net.ACC file is 
missing. 
NERR_UserNotFound 2221 The user name cannot 
be found. 
NERR_ACFNotLoaded 2221 The UAS database has 
not been started. 
NERR_ACFFileIOFail 2229 An error was 


encountered in 
accessing the accounts 


database. 

NERR _InvalidComputer 2351 The specified computer 
name is invalid. 

NERR _InvalidUASOp 2451 This operation is not 


permitted when the 
Netlogon service is 
running. 


NERR_NetLogonNotStarted 2455 The Netlogon service 
has not been started. 
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Manifest Value Meaning 


NERR_CanNotGrowUASFile 2456 It is not possible to 
grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

e DosFreeSeg 

¢ DosFsCtlh(NETTRANSACTION) 

¢ DosFsCtl(NULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_ FILE NOT_FOUND] 
¢ DosNewSize[-ERROR_DISK_FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 


¢ DosWrite. 
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Error Logging Category 


Description 


Data Structures 


NetErrorLogClear (admin)—See “NetErrorLogClear” on page 3-90. 
NetErrorLogRead (admin)—See “NetErrorLogRead” on page 3-93. 
NetErrorLogWrite (/ocal)—See “NetErrorLogWrite” on page 3-97. 


The functions in the Error Logging category control the error log file. They are 
used with the ERRLOG.H and NETCONS.H include files. 


Each time an error condition occurs during a network operation, an error log entry 
can be generated by NetErrorLogWrite to record error information. The other two 
functions enable opening (NetErrorLogRead) and clearing (NetErrorLogClear) of 
the error log file (which stores the entries). 


Error log entries are stored as ASCII text. The default error log file name is 
\IBMLAN\LOGS\NET.ERR. All error logging functions perform their operations 
on this file. 


Note: The error logging functions control changes to the error log file only. To 
read the error log file, an application must first call the NetErrorLogRead 
function to obtain the handle of the file. The DosRead function can then be 
called to read the file. To close the file, an application must call the 
DosClose function. 


The error log file contains information about the following types of errors: 
¢ OS/2 LAN Requester/Server software internal errors 
e OS/2 internal errors 


e Network service errors. 


The NetErrorLogWrite function uses the error_log data structure to write an entry to 
the error log file. The entry consists of a fixed-length data structure optionally 
followed by zero or more ASCIIZ strings (e/_text) describing the error message and 
a block of raw data (el_data) relating to the cause of the error. Because of the 
variable lengths and structures of the e/_data and el_text portions of the entry, only 
the fixed-length data structure is defined in the error_log data structure. 
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The fixed portion of the error log entry has the following format: 


struct error_log { 

unsigned short el_len; 

unsigned short el_reserved; 

unsigned long el_time; 

unsigned short el_error; 

char el_name[SNLEN+1] ; 
----- unsigned short el_data_offset; /* offset from beginning 

address of error_log */ 

unsigned short el_nstrings; 


/* variable-length data specific to the error 
message and block of data associated with error */ 


char el_text []; /* error message */ 
--> char el_data []; /* raw data - the number of bytes 
used for raw data is equivalent to: 
size = el_len - (el_data_offset 
+ sizeof(el_len) ); */ 
unsigned short el_len; 


where: 


e el_len indicates the length (in bytes) of the error log entry. (Note that e/_len is 
included at both the beginning and end of the entry to enable both forward and 
backward scanning of the file.) 


e el_reserved is reserved. 
¢ el_time indicates the time when e/_name submitted the error entry. 


e el_error is the error code for the error. e/_error can be used to obtain an error 
message from the NET.MSG file. 


e el_name is an ASCIIZ string indicating the name of the network service or 
application that returned the error entry. 


¢ el _data_offset specifies the byte offset from the beginning of the error log entry 
to the start of its variable-length portion (e/_data). 


¢ el_nstrings indicates the number of ASCIIZ strings the el_text portion of the 
entry contains. 


¢ el_text points to.zero or more ASCIIZ strings describing the error. 


¢ el data points to the raw data associated with the error. 


Related Information 
For information on error codes, see Appendix C, “Return Codes.” 
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NetErrorLogClear 
The NetErrorLogClear (admin) function clears (and optionally saves) the error log 


Syntax 


Return Codes 


file of a computer. 


#include <netcons.h> 
#include <errlog.h> 


unsigned far pascal 


NetErrorLogClear(servername, backupfile, reserved) 


const char far * servername; 
const char far * backupfile; 
char far * reserved; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


computer. 


¢ backupfile points to an ASCIIZ string assigning a name for an optional backup 
file. The calling application must have Write privileges for the path specified by 
backupfile. The path name must also be accessible by the OS/2 DosMove 
function. If the path name is relative, it is assumed relative to the 


IBMLAN\LOGS directory. 


A NULL pointer indicates that NetErrorLogClear is not to save the error log 


entries. 


e reserved is a NULL pointer. 


Manifest 
NERR_SUCCESS 


ERROR_ACCESS DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_SHARING VIOLATION 


ERROR_NOT_SUPPORTED 


ERROR_BAD_NETPATH 


ERROR_NETWORK_ACCESS DENIED 


ERROR_BAD_NET_NAME 


ERROR_INVALID_PARAMETER 
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Value 


32 


50 


53 


65 


67 


87 


Meaning 

No errors were 
encountered. 
Administrative 
privilege is required. 
Sufficient memory is 
not available. 


A sharing violation 
occurred. 


This request is not 
supported by the 
network. 


The network path 
cannot be found. 


Network access is 
denied. 


This network name 
cannot be found. 


The specified 
parameter is invalid. 


Manifest 
ERROR_NET_WRITE_FAULT 


ERROR_INVALID_ NAME 


ERROR_INVALID_LEVEL 


ERROR_FILENAME EXCED RANGE 


ERROR_MORE_ DATA 


NERR _NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmall 


NERR_OS2loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_InvalidComputer 


NERR_CantType 


Value 
88 


123 


124 


206 


234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2351 


2351 


Meaning 


A network data fault 
has occurred. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The specified computer 
name is invalid. 


The type of input 
cannot be determined. 
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Remarks 


Related Information 


Other error return codes may be returned from the following OS/2 functions: 


DosDelete 

DosFsRamSemClear 

DosFreeSeg . 
DosFsCtl(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosNewSize[-ERROR_DISK_FULL] 
DosMove 

DosOpen 

DosSemClear 


redir.GetNetInitPath. 


NetErrorLogClear fails if the error log file is currently opened by another process. . 
The NetErrorLogWrite function (see “NetErrorLogWrite” on page 3-97) issues an 
admin alert when the error log file reaches 80% capacity and again when the file 
reaches 100% capacity. At 100% error log file capacity, NetErrorLogWrite fails. 

_ Therefore, applications should periodically clear the error log file of outdated 


information. 


To set a maximum size for the error log file, use one of the following methods: 


Use the NET CONFIG command with the /MAXERRORLOG option (see the 
IBM Operating System/2 Local Area Network Server Version 1.2 Network 
Administrator's Guide for more information). 


Set the maxerrorlog parameter in the IBMLAN._INI file (see the JBM Operating 
System/2 Local Area Network Server Version 1.2 Network Administrator's Guide 
for a description of the IBMLAN._INI file). 


Call the NetWkstaSetInfo function with the wki0_errlogsz parameter. 


For information on writing an entry to the error log file, see “NetErrorLog Write” 
on page 3-97. 
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NetErrorLogRead 
The NetErrorLogRead (admin) function opens and returns an OS/2 file handle to 
the error log file of a computer . 


Syntax 


#include <netcons.h> 
#include <errlog.h> 


unsigned far pascal 


NetErrorLogRead (servername, reservedl, ploghnd]l, offset, reserved2, 
reserved3, flags, buf, buflen, bytesread, bytesavail) 


const char far * servername; 
const char far * reservedl 
HLOG far * ploghnd1; 
unsigned long offset; 
unsigned short far * reserved2; 
unsigned long reserved3; 
unsigned long flags; 
char far * buf; 
unsigned short buflen; 
unsigned short far * bytesread; 


unsigned short far * 


bytesavail; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the 
local server. 


e reserved] must be a NULL pointer. 
¢ ploghndl is the pointer to the returned log handle. 


¢ offset is the record offset to begin read. The offset is ignored unless flags bit 1 is 
set. If this bit is set, offset is taken as a zero-based offset based on record 
number rather than bytes, at which the data returned should begin. Note that 
the record offset parameter is zero based from both directions, dependent upon 
the direction of the read. If reading backwards is specified, then the Oth record 
is the last record in the file. If reading forward, then the Oth record is the first 
record in the file. 


e reserved2 must be a NULL pointer. 

¢ reserved3 must be zero. 

¢ flags specifies the open flags, bitmapped as shown here. 

® buf is the pointer to the buffer for returned data. 

¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ bytesread points to an unsigned short integer indicating the number of bytes read 
into the buffer. 


¢ bytesavail points to an unsigned short integer indicating the number of bytes 
available. 
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The bitmapped flags fields are as follows: 


Bits Meaning 


0 If 0, the file is read normally. If 1, the file is read backwards and 
records are returned in the buffer in reverse-chron order (newest 
records first). 


1 If 0, read proceeds normally and sequentially. If 1, read proceeds from 
the Nth record from the start of the file. “N” is the offset parameter. 
2-31 Reserved; must be 0. 


The offset is ignored unless flags bit 1 is set. If this bit is set, offset is taken as a 
zero-based offset based on record number, not bytes, at which the data returned 
should begin. 


An application calling NetErrorLogRead for the first time must initialize the 64-bit 
log handle as follows: 


Bits Value 
127 (MSB)-64 0 
63-0(LSB) L 


Where the least significant bit (LSB) is the last (rightmost) bit. Thereafter, each call 
to NetErrorLogRead must be given the value for the log handle that was returned 
by the previous call to NetErrorLogRead. 


Note: If bytesread is 0 and bytesavail is not 0, the buffer is too small to hold the 
next record in the file. 


Unlike other API uses of bytesavail, in this case, the value may be OxFFFF, 
which is shorthand for “OxFFFF or more.” There can potentially be much 
more than 64KB of data available. The application should continue to 
process entries until this value is returned to 0. 


The data is returned in the buffer. The application should use the bytesread value to 
determine the end of valid data in the buffer. 


Return Codes 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR _ACCESS_DENIED > Administrative 
privilege is required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 

ERROR_BAD_NETPATH 53 The network path 
cannot be found. 

ERROR_NETWORK_ACCESS_DENIED 65 Network access is 
denied. 
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Manifest 
ERROR _BAD_NET_ NAME 


ERROR_INVALID_ PARAMETER 


ERROR_NET_WRITE_FAULT 


ERROR_INVALID_NAME 


ERROR_INVALID_LEVEL 


ERROR_FILENAME_ EXCED RANGE 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ ShareMem 


NERR_BufTooSmall 


NERR_OS82IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR InvalidComputer 


NERR_CantType 


Value 
67 


87 


88 


123 


124 


206 


234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2351 


2357 


Meaning 


This network name 
cannot be found. 


The specified 
parameter is invalid. 


‘A network data fault 


has occurred. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


The type of input 
cannot be determined. 
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Manifest Value Meaning 


NERR_LogFileChanged 2378 This log file has 
changed between reads. 

NERR_LogFileCorrupt 2379 This log file is corrupt. 

NERR _InvalidLogSeek 2440 The log file does not 


contain the requested 
record number. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosChgFilePtr 

DosClose 

DosFsRamSemClear 

DosFreeSeg 
DosFsCtl(NETTRANSACTION) 
DosFsCtlh((NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_ NOT_FOUND] 
DosOpen 

DosRead 

DosSemClear 


redir.GetNetInitPath. 


After the NetErrorLogRead function returns the handle of the error log file , an 
application calls the DosRead function to read the contents of a file. To close the 
file, an application must call the DosClose function. 


Related Information 


For information on: 


Clearing an error log file—See “NetErrorLogClear” on page 3-90. 


Closing an error log file—See DosClose in the IBM Operating System/2 Technical 
Reference Version 1.2 Programming Reference. 


Reading an error log file—See DosRead in the IBM Operating System[2 
Technical Reference Version 1.2 Programming Reference. 
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NetErrorLogWrite 


Syntax 


Return Codes 


The NetErrorLogWrite (local) function writes an entry to the error log file of a 
computer. 


#include <netcons.h> 
#include <errlog.h> 


unsigned far pascal 

NetErrorLogWrite(reservedl, code, component, buf, buflen, 
insbuf, nstrings, reserved2) ; 

char far * reservedi; 

unsigned short code; 

const char far * component; 

const char far * buf; 

unsigned short  buflen; 

const char far * insbuf; 

unsigned short nstrings; 

char far * reserved23 


where: 
e reserved] must be a NULL pointer. 
e code specifies the error code of the network error that occurred. 


© component points to an ASCIIZ string specifying which software component 
encountered the error. 


e buf points to the raw data associated with the error condition. 

¢ buflen specifies the size (in bytes) of the buf memory area. 

¢ insbuf points to the ASCIIZ strings containing the error message. 

e nstrings indicates the number of concatenated ASCIIZ strings insbuf stores. 


¢ reserved2 must be a NULL pointer. 


Manifest Value Meaning. 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative. 
privilege is required.. 
ERROR_ INVALID PARAMETER 87 The specified 
parameter is invalid. 
NERR _NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR. WkstaNotStarted 2138 The Requester service 
has not been started. 
NERR_LogonNoUserPath 2211. The server is 


configured without a 
valid user path. 
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Manifest Value Meaning 
NERR_LogOverflow 2377 This log file exceeds 


Remarks 


the maximum defined 
size. 


The NetErrorLogWrite function internally calls the appropriate OS/2 functions to 
open and close the error log file. 


The NetErrorLogWrite function issues an error log alert (with NetAlertRaise) each 
time an entry is written to the error log file. Also, the NetErrorLogWrite function 
issues an admin alert by calling the NetAlertRaise function when the error log file 
reaches 80% capacity and again when the file reaches 100% capacity. At 100% error 
log file capacity, NetErrorLogWrite fails, returning the error code 
NERR_LogOverflow. 


Related Information 


For information on: 


Clearing the error log file—See “NetErrorLogClear” on page 3-90. 


Closing the error log file—See DosClose in IBM Operating System/2 Technical 
Reference Version 1.2 Programming Reference. 


Error codes—See Appendix C, “Return Codes.” 
Limiting the size of the error log file—See “NetServerSetInfo” on page 3-295. 


Retrieving the size of the error log file—See “NetServerGetInfo” on page 3-292. 


3-98 LAN Server Application Programmer’s Reference 


File Category 


Description 


Data Structures 


NetFileClose2 (admin, server, DOS)—See “NetFileClose2” on page 3-101. 
NetFileEnum2 (admin, server, DOS)—See “NetFileEnum2” on page 3-104. 
NetFileGetInfo2 (admin, server, DOS)—See “NetFileGetInfo2” on page 3-107. 


The functions in the File category provide a system for monitoring which file, device, 
and pipe resources are opened on a server and for closing one of these resources if 
necessary. They are used with the SHARES.H and NETCONS.H include files. 


NetFileGetInfo2 returns information on one particular opening of a resource. Two 
levels of detail are available, yielding only the identification number assigned to the 
resource when it was opened (level 2) or additional data on permissions, file-locks, 
and who opened the resource (level 3). 


NetFileClose2 forces a resource closed when a system error prevents normal closure 
by the DosClose function. 


The level parameter for NetFileEnum2 and NetFileGetInfo2 specifies one of two 
levels of information (2 or 3) to be returned. Both functions return data structured 
as follows: 


Opened Resources (Level 2) 


struct file_info_2 { 
unsigned long fi2_id; 
hs 

where: 


¢ fi2_id is the identification number assigned to the resource at opening. 


Opened Resources (Level 3) 


struct file_info_3 { 
unsigned long fi3_id; 
unsigned short fi3_permissions; 
unsigned short fi3_num_locks; 


char far * fi3_pathname; 
char far * fi3_username; 
}; 
where: 


¢ fi3_id is the identification number assigned to the resource at opening. 
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-@ fi3_permissions indicates the access permissions of the opening application. The 
bit mask of fi3_permissions is defined in SHARES.H as follows: 


Manifest Bitmask Meaning 

FILE_READ 0x1 Permission to read a resource, 
and by default, execute the 
resource. 

FILE_WRITE 0x2 Permission to write to a 
resource. 

FILE_CREATE 0x4 Permission to create a resource; 


data can be written when 
creating the resource. 


¢ fi3_num_locks indicates the number of file-locks on the file, device, or pipe. 


¢ fi3_pathname points to an ASCIIZ string giving the path name of the opened 
resource. 


e fi3_username points to an ASCIIZ string indicating the user that opened the 
resource. 
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NetFileClose2 


Syntax 


Return Codes 


The NetFileClose2 (admin, server, DOS) function forces a resource closed when a 
system error prevents a normal DosClose function closing. 


#include <netcons.h> 
#include <shares.h> 


unsigned far pascal 
NetFileClose2(servername, fileid) 
const char far * servername; 
unsigned long’ fileid; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ fileid is the identification number assigned to the resource at opening. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_NETWORK_ ACCESS DENIED 65 Network access is 
denied. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR _NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 


net been started. 


NERR_ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 

NERR _ServerNotStarted 2114 The Server service has 


not been started. 
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Manifest Value Meaning 


NERR_BufTooSmall 2123 The buffer is too small 
for fixed-length data. 
NERR_OS2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR _InvalidAPI 2142 The requested API is 


not supported on the 
remote server. 


NERR_FileIdNotFound 2314 There is not an open 
file with that ID 
number. 


NERR _ InvalidComputer 2351 The specified computer 
name is invalid. 


NERR_NoSuchServer 2460 The server ID is not 
valid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
e DosFreeSeg 
* DosFsCth(NETTRANSACTION) 
¢ DosFsCthNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 
Remarks 
Normally, the DosClose function is used to close a resource opened by a call to the 


DosOpen function. Use NetFileClose2 to force closed a resource opened by another 
process. 
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Related Information 
For information on listing all open files and their identification numbers for a server, 
see “NetFileEnum2” on page 3-104. 
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NetFileEnum2 


The NetFileEnum2 (admin, server, DOS) function supplies information about some 
or all open files on the server, allowing the user to supply a key to get the required 
information through iterated calls to the API. 


Syntax 


#include <netcons.h> 
#include <shares.h> 


unsigned far pascal 
NetFileEnum2( sc. -ername, basepath, username, level, flags, buf, 


buflen, entriesread, totalentries, resume_key ) 


char far * servername; 
char far * basepath; 
char far * username; 
short level; 

char far * buf; 

unsigned short buflen; 
unsigned short far * entriesread; 
unsigned short far * totalentries; 
void far * resume_key; 
where: 


Servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


basepath is the base path for enumeration. If non-NULL, basepath serves as a 
qualifier to the enumeration. The entries returned are limited to those whose 
name begins with the qualifier string. For example, a basepath of C:TMP would 
enumerate only open files whose pathnames begin with C:TMP, including 
C:TMPFILE and C:\TMP\DOCUMENT. 


username points to an ASCIIZ string indicating the name of the user. If 
non-NULL, username serves as a qualifier to the enumeration. The files 
returned are limited to those whose opener username matches the qualifier. 


level specifies the level of detail (2 or 3) in the file_info_ data structure. 
buf points to the file_info_2 or file_info_3 data structure. 
buflen specifies the size (in bytes) of the buf memory area. 


entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


resume_key is a pointer to structure FRK (structure res_file_enum2). This field is 
used for continuing scanning. 
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Return Codes 


Remarks 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 

ERROR INVALID PARAMETER 87 The specified 
parameter is invalid. 

ERROR_INVALID LEVEL 124 The Level parameter is 
invalid. 

ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR _NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 

NERR ServerNotStarted 2114 The Server service has 


not been started. 


This API provides a way for the user to overcome the problem arising when the 
information returned exceeds 64KB. To initialize the key resume_key, use the 
macroinstruction FRK_INIT supplied in the file SHARES.H, which accepts a 
structure FRK as an argument. The following is an example of an application code 
segment: 


FRK f; 


FRK_INIT ( f ); 
NetFileEnum2 ( ..., &f, ... )3 


When invoked with an initial resume key, if the supplied buffer is too small to return 
all the requested information, the NetFileEnum2 function returns the error code 
ERROR MORE DATA and a resume_key suitable for retrieving the remaining 
data. When invoked with a resume_key from a previous call, it resumes the 
enumeration where indicated by *resume_key The user must not attempt to set this 
key other than to initialize it. Other values of *resume_key supplied by the user 
must have been returned by a preceeding call to NetFileEnum2. 


NetFileEnum? never returns an entry that has partial. data; that is, a fixed-length 
data record and all variable-length data is present for each returned item. Items that 
cannot fit completely are not returned in the buffer. This differs from normal Enum 
function calls, which return partial data for some entries, usually the last few, if the 
buffer is too small. The reason that Enum? differs is because the entries can be 
retrieved in full by subsequent calls (using the resume_key), and so partial data could 
be misleading and is less useful than in normal Enum functions. 


The username parameter, if not NULL, serves as a qualifier to the enumeration. The 
files returned are limited to those whose opener user name matches the qualifier. 


The basepath parameter, if not NULL, serves as a prefix to qualify the enumeration. 
The entries returned are limited to those whose names begin with the qualifier string. 
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For example, a basepath of “C:\TMP” would enumerate only open files whose path 
names begin with “C:\TMP,” including “C:\TMPFILE” and 
“C:\TMP\DOCUMENT.” 


If both the username and the basepath parameters are specified, only the files 
matching both the qualifying conditions are returned. 
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NetFileGetinfo2 


Syntax 


Return Codes 


The NetFileGetInfo2 (admin, server, DOS) function retrieves information about a 
particular opening of a server resource. 


#include <netcons.h> 
#include <shares.h> 


unsigned far pascal 
NetFileGetInfo2(servername, fileid, level, 
buf, buflen, totalavail) 


const char far * servername; 
unsigned long fileid; 
short level; 

char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ fileid indicates the identification number assigned to the resource at opening. 


¢ level specifies the level of detail (2 or 3) to be returned by the file_info data 
structure. 


¢ buf points to the file_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 


supported by the 
network. 


Network access is 
denied. 


The specified 
parameter is invalid. 


ERROR_NETWORK_ACCESS_ DENIED 65 
ERROR_INVALID_PARAMETER 87 


124 


ERROR_INVALID_LEVEL The Level parameter is 


invalid. 
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Manifest 
ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR _ ServerNotStarted 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR _ FileIdNotFound . 


NERR_InvalidComputer 
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Value 
234 


2102 


2104 


2106 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2314 


2351 


Meaning 
Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared » 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service. has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


There is not an open 
file with that ID 
number. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Related Information 


DosFSRamSemClear 

DosFreeSeg 

DosFsCtl 

DosFsCth(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


For information on: 


Closing a file, device, or pipe—See “NetFileClose2” on page 3-101. 


Listing files, devices, or pipes open on a server—See “NetFileEnum2” on 
page 3-104. 
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Group Category 


Description 


NetGroupAdd (admin, DOS)—See “NetGroupAdd” on page 3-112. 
NetGroupAddUser (admin, DOS)—See “NetGroupAddUser” on page 3-115. 
NetGroupDel (admin, DOS)—See “NetGroupDel” on page 3-118. 

NetGroupDelUser (admin, DOS)—See “NetGroupDelUser” on page 3-121. 
NetGroupEnum (partially admin, DOS)—See “NetGroupEnum” on page 3-124. 
NetGroupGetInfo (partially admin, DOS)—See “NetGroupGetInfo” on page 3-127. 
NetGroupGetUsers (partially admin, DOS)—See “NetGroupGetUsers” on page 3-130. 
NetGroupSetInfo (admin, DOS)—See “NetGroupSetInfo” on page 3-133. 
NetGroupSetUsers (admin, DOS)—See “NetGroupSetUsers” on page 3-136. 


The functions in the Group category control user groups in the user accounts 
subsystem (UAS) database. They are used with the ACCESS.H and NETCONS.H 
include files. 


A group is a set of users sharing common permissions in the UAS database. The 
Group functions create or delete groups and review or adjust their membership. 


Access permissions can be assigned for all members of a group by supplying the 
group name to the NetAccessAdd function (see “Access Permission Category” on 
page 3-2) instead of individually assigning each user an access permission record. 


Note: The OS/2 LAN Requester/Server software maintains special groups to which 
any user assigned USER or ADMIN privileges is added automatically. If an 
application calls any of the Group functions in an attempt to modify the 
group USERS, the group ADMIN, or their membership, the function returns 
the NERR_SpeGroupOp error code. 


To create a user group, an application calls the NetGroupAdd function, supplying a 
group name. Initially, the group has no members. Members are assigned to the 
group by calling NetGroupAddUser. 


NetGroupDelUser removes the name of a specified user from a group, and 
NetGroupDel disbands a group. (NetGroupDel works regardless of whether or not 
the group has members.) 


Two functions retrieve information about groups on a server. NetGroupEnum 
produces a list of all groups. NetGroupGetUsers lists all members of a specified 
group. 
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Special Groups 
There are three special groups: USERS, ADMINS, and GUESTS. Each user 
account automatically belongs to one of these three special groups according to the 
user’s privilege level. The members of these special groups must have one of the 
following privilege levels: 


¢ USER PRIV_USER 
° USER _PRIV_ADMIN 
¢ USER _PRIV_GUEST. 


Users cannot be deleted from these groups, nor can groups be deleted. An attempt 
to delete groups or users in these groups causes the NERR_SpeGroupOp error code 
to be returned. 


Data Structures 
Only three of the Group functions—NetGroupAdd, NetGroupEnum, and | 
NetGroupGetUsers—return structured data. The simple data structures that these 
functions use are described following the syntax description for each function. 


Group Information (Level 0 and Level 1) 
The basic data structures for Group information are as follows: 


struct group_info_0 { 

char grpi0_name[GNLEN+1]; 
}; 
where: 


¢ grpi0_name is the name of the group. 


struct group_info_1 { 


char grpil_name[GNLEN+1]; 
char grpil_pad_1; 
char far * grpil_comment; 

}; 

where: 


e grpil_name is the name of the group. 
¢ grpil_pad_1 is for the WORD-alignment in the data structure. 


¢ grpil_comment points to an ASCIIZ string containing the comment or remark of 
the group. The string can be NULL. 


Group Membership Information (Level 0) 
The basic data structure for Group Membership information is as follows: 


struct group_users_info 0 { 
char grui0_name[UNLEN+1] ; 
}3 


where: 


¢ grpi0_name is the name of the user in the group. 


All of these functions should be used with the ACCESS.H and NETCONS.H include 
files. 
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NetGroupAdd 


The NetGroupAdd (admin, DOS) function creates a new group account in the user 
accounts subsystem (UAS) database. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGrounAdd (servername, level, buf, buflen) 


char far * servername; 
short level; 
char far * buf ; 


unsigned short buflen; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


e level specifies the level of detail (0 or 1) for the group_info data structure. 
e buf points to the group_info data structure. 


When adding at level 0, the comment field is set to the empty string, since no 
comment field is provided in the level 0 structure. 


e bufien specifies the size (in bytes) of the buf memory area. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_BAD_NETPATH 53 The network path 
cannot be found. 
ERROR_NETWORK_ACCESS DENIED 65 Network access is 
denied. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR _NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS82IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_BadUsername 


NERR _ GroupExists 
NERR_UserExists 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 


NERR_ACFFileIlOFail 


Value 
2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2202 


2223 


2224 


2226 


Z2n1 


2228 


2229 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error - 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested. 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested APT is 
not supported on the 
remote server. 


The user name or 
group name parameter. 
is invalid. 


The group name is 
already in use. 


The user account 
already exists. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file.. 


An error was © 
encountered in 
accessing the accounts 
database: 
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Manifest Value Meaning 


NERR InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


NetGroupAdd will fail if the name already is used as a user name. User names and 
group names must be unique. 


Related Information 


For information on: 


Adding a user to a group—See “NetGroupAddUser” on page 3-115. 
Assigning group permissions—See “NetAccessAdd” on page 3-6. 
Deleting a group account from a server—See “NetGroupDel” on page 3-118. 


Listing all groups on a server—See “NetGroupEnum” on page 3-124. 
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NetGroupAddUser 
The NetGroupAddUser (admin, DOS) function adds a user to a group in the user 


Syntax 


Return Codes 


accounts subsystem (UAS) database. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 


NetGroupAddUser(servername, groupname, username) 


char far * servername; 
char far * groupname; 
char far * username; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 


Server. 


¢ groupname points to an ASCIIZ string specifying the group the user will join. 


° username points to an ASCIIZ string specifying the user to add to the group. 


Manifest 
NERR_SUCCESS 


ERROR_ACCESS DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_SEEK 
ERROR_INVALID PARAMETER 


ERROR_INVALID NAME 


ERROR_INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


Value 
0 


25 
87 


123 


124 


234 


2102 


2104 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


The seek is invalid. 


The specified 
parameter is invalid. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 
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‘Manifest 


NERR_RemoteOnly 


‘NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


‘NNERR_GroupNotFound 


NERR_UserNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_SpeGroupOp 


NERR_UserInGroup 


NERR_InvalidDatabase 


NERR_InvalidComputer 


NERR_CanNotGrowUASFile 
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Value 
2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2220 


PPI 


2226 


2227 


2229 


2234 


2236 


2247 


2351 


2456 


Meaning 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 


_has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The group does not 
exist. 


The user name cannot 
be found. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


This operation is not 
allowed on this special 
group. 

The user already 
belongs to this group. 


The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


It is not possible to 
grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosAllocSeg 

DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 
DosFsCth(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosNewSize[-ERROR_DISK_ FULL] 
DosQFileInfo 

DosRead 

DosSemClear 


DosWrite. 


If any attempt is made to add a user name to the special groups (USERS, ADMINS, 
or GUESTS), the NetGroupAddUser function returns the NERR_ SpeGroupOp 
error code. 


Related Information 


For information on: 


Creating a new group—See “NetGroupAdd” on page 3-112. 


Defining group access permission records—See “Access Permission Category” on 
page 3-2. 


Removing a user from a group—See “NetGroupDelUser” on page 3-121. 


Retrieving a list of the members of a group—See “NetGroupGetUsers” on 
page 3-130. 


Setting the groups of which a user is a member—See “NetUserSetGroups” on 
page 3-423. 
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NetGroupDel 
The NetGroupDel (admin, DOS) function removes a group account from the user 
accounts subsystem (UAS) database. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 

NetGroupDel (servername, groupname) 
char far * servername; 

char far * groupname; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


* groupname points to an ASCIIZ string specifying which group to remove. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK pds) The seek is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_FILENAME_ EXCED_ RANGE 206 The file name is longer 


than 8 characters or 
the extension is longer 
than 3 characters. 


ERROR_ MORE DATA 234 Additional data is 
available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 

NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 
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Manifest 
NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR InvalidAPI 


NERR_GroupNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_SpeGroupOp 


NERR _InvalidDatabase 


NERR_InvalidComputer 


NERR_CanNotGrowUASFile 


Value 
2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2220 


2226 


2221 


2229 


2234 


2247 


2351 


2456 


Meaning 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The group does not 
exist. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


This operation is not 
allowed on this special 
group. 

The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


It is not possible to 
grow the UAS file. 


Chapter 3. API Function Descriptions 3-119 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 

DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosNewSize[-ERROR_DISK_FULL] 
DosSemClear 


DosWrite. 


It is not necessary to remove all members from a group before deleting the group 
account. 


Deleting a group account does not delete the individual accounts of its member 
users. 


Deleting a group deletes it from the access control profiles. 


NetGroupDel returns the NERR_SpeGroupOp error code if any attempt is made to 
remove the special groups (USERS, ADMINS, or GUESTS). 


Related Information 
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For information on: 


Adding a group to the UAS database—See “NetGroupAdd” on page 3-112. 
Listing all groups in the UAS database—See “NetGroupEnum” on page 3-124. 
Removing a user from a group—See “NetGroupDelUser” on page 3-121. 


Retrieving a list of members for a group—See “NetGroupGetUsers” on 
page 3-130. 
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NetGroupDelUser 
The NetGroupDelUser (admin, DOS) function removes a user from a particular 
group in the user accounts subsystem (UAS) database. 


Syntax 


Return Codes 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 


NetGroupDelUser(servername, groupname, username) 


char far * servername; 
char far * groupname; 
char far * username; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 


server. 


¢ groupname points to an ASCIIZ string specifying the group to be altered. 


© username points to an ASCIIZ string specifying which user to remove from the 


group account. 


Manifest 
NERR_SUCCESS 


-ERROR_ACCESS_ DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_SEEK 
ERROR_INVALID PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


Value 


25 
87 


124 


234 


2102 


2104 


2106 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


The seek is invalid. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 
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Manifest 
NERR_BufTooSmall 


NERR_OSZIoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_GroupNotFound 
NERR_UserNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_SpeGroupOp 


NERR_UserNotInGroup 
NERR_InvalidDatabase 


NERR_InvalidComputer 
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Value 
2123 


2134 


2138 


2139 


2140 


2141 


2142 


2220 


2221 


2226 


2227 


2229 


2234 


2237 


2247 


2351 


Meaning 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The group does not 
exist. 


The user name cannot 
be found. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


This operation is not 
allowed on this special 
group. 


The user does not 
belong to this group. 


The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
e DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCtlhNETTRANSACTION) 

¢ DosFsCtlhNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize[-ERROR_DISK_ FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 


e DosWrite. 


Remarks 
Removing a user from a group does not delete the user’s account in the system. 


If an application tries to delete a user name from the special groups (USERS, 
ADMINS, or GUESTS), NetGroupDelUser returns the NERR_SpeGroupOp error 
code. 


Related Information 
For information on: 
e Adding a user to a group—See “NetGroupAddUser” on page 3-115. 
e Deleting a group—See “NetGroupDel” on page 3-118. 


¢ Retrieving a list of members of a group—See “NetGroupGetUsers” on 
page 3-130. 
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NetGroupEnum 


Syntax 


Return Codes 


The NetGroupEnum (partially admin, DOS) function lists. all group accounts on the 
user accounts subsystem (UAS) database. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGroupEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 

char far * buf; 

unsigned short buflen; 
unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
server. 


e level specifies the level of detail (0 or 1) for the group_info data structure. 
e buf points to the group_info data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
available. 


On successful returns, buf contains entriesread number of group_info data structures. 


Manifest. Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR _BAD_NETPATH 53 The network path 


cannot be found. 


Network access is. 
denied. 


ERROR_NETWORK_ACCESS_DENIED 65 


ERROR_INVALID_ PARAMETER 87 The specified 


parameter is invalid. 
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Manifest 
ERROR _ INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR _BadTransactConfig 


NERR_InvalidAPI 


NERR_ GroupNotFound 


NERR NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 


NERR_ACFFileIOFail 


Value 
124 


234 


2102 


2104 


2106 


2134 


2138 


2139 


2140 


2141 


2142 


2220 


2226 


2227 


2228 


2229 


Meaning 


The Level parameter is 
invalid. 


Additional data is 
available, but the 


buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The group does not 
exist. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


An error was 
encountered in 
accessing the accounts 
database. 
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Manifest Value Meaning 


NERR_InvalidDatabase 2247 The UAS database file 
is corrupted. 
NERR_InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 

DosFsCth(NETTRANSACTION) 
DosFsCth(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosRead 


DosSemClear. 


Only the group names can be retrieved with ordinary user’s privilege. With 
administrative privilege, the comments can be returned. 


Related Information 


For information on: 


Adding a new group to the UAS database—See “NetGroupAdd” on page 3-112. 
Removing a group from the UAS database—See “NetGroupDel” on page 3-118. 
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NetGroupGetinfo 
The NetGroupGetInfo (partially admin, DOS) retrieves group-related information. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGroupGetInfo (servername, groupname, level, buf, buflen, 


totalavail) 
char far * servername; 
char far * groupname; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
server. 


© groupname points to an ASCIIZ string specifying the group from which to get 
information. 


¢ level specifies the level of detail (0 or 1) for the group_info data structure. 
e buf points to the group_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR _ INVALID PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
NERR _NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_GroupNotFound 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 


NERR_ACFFileIOFail 


NERR_SpeGroupOp 


NERR_InvalidComputer 
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Value 
2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2220 


2227 


2228 


2229 


2234 


2351 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The group does not 
exist. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


An error was 
encountered in 
accessing the accounts 
database. 


This operation is not 
allowed on this special 
group. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 
¢ DosFreeSeg 
e DosFsCth(NETTRANSACTION) 
¢ DosFsCth(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 
Remarks 
A user without administrative privilege can call this API only with level 0 on a 


remote call. Users cannot issue this function on the groups to which they do not 
belong. 
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NetGroupGetUsers 
The NetGroupGetUsers (partially admin, DOS) function returns a list of members 
of a particular group in the user accounts subsystem (UAS) database. Users can 
perform this function on groups to which they belong. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGroupGetUsers(servername, groupname, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
char far * groupname; 
short level; 
char far * buf ; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
server. 


* groupname points to an ASCIIZ string specifying the name of the group whose 
members will be listed. 


e level specifies the level of detail (0) for the group_users_info_O data structure. 
¢ buf points to the group_users_info_0 data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


° entriesread points to an unsigned short integer indicating the number of entries 
returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 


available. 
Return Codes 

Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 

ERROR _ SEEK 25 The seek is invalid. 

ERROR_BAD_NETPATH 53 The network path 
cannot be found. 

ERROR_NETWORK_ACCESS_DENIED 65 Network access is 
denied. 
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Manifest 
ERROR_INVALID_ PARAMETER 


ERROR_INVALID_ LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmail 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_ACFNotFound 


NERR_GroupNotFound 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 


NERR_ACFFileIOFail 


Value 


124 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2219 


2220 


2227 


2228 


2229 
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Meaning 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The Net.ACC file is 
missing. 


The group does not 
exist. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


An error was 
encountered in 
accessing the accounts 
database. 
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Manifest Value Meaning 


NERR_InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 
e DosChgFilePtr 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCthINULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosRead 


¢ DosSemClear. 


Remarks 
This is functionally equivalent to an Enum call because it enumerates the users in a 
group. See “NetGroupEnum” on page 3-124. NetGroupGetUsers of the special 
groups USERS, ADMINS, and GUESTS is an admin call. 


Related Information 
For information on: 


e Listing all groups to which a user belongs—See “NetGroupGetUsers” on 
page 3-130. 


¢ Listing the names of groups in the UAS database—See “NetGroupEnum” on 
page 3-124. 
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NetGroupSetinfo 


Syntax 


Return Codes 


The NetGroupSetInfo (admin, DOS) function sets group-related information. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGroupSetInfo (servername, groupname, level, buf, buflen, 


parmnum) 
char far * servername; 
char far * groupname; 
short level; 
char far * buf; 
unsigned short buflens; 
short parmnums; 
where: 


servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
server. 


groupname points to an ASCIIZ string specifying the group to set the 
information. 


level specifies the level of detail (1) for the group_info data structure. 


buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


buflen specifies the size (in bytes) of the buf memory area. 


parmnum determines whether buf contains a complete group_info data structure 
or a single data structure component. If parmnum is 0, buf must contain the 
group_info_1 data structure. The only settable field is comment. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_ LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


3-133 


Chapter 3. API Function Descriptions 


Manifest Value Meaning 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 

NERR _ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 

NERR_BufTooSmall 2123 The buffer is too small 
for fixed-length data. 

NERR_OSZ2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR _InvalidAPI 2142 The requested API is 


not supported on the 
remote server. 


NERR_GroupNotFound 2220 The group does not 
exist. 

NERR_UserNotFound 2221 The user name cannot 
be found. 

NERR_NotPrimary 2226 The UAS database is 


replicant and will not 
allow updates. 


NERR_ACFNotLoaded 2227 The UAS database has 
not been started. 
NERR_ACFFileIOFail 2229 An error was 


encountered in 
accessing the accounts 
database. 


NERR_SpeGroupOp 2234 This operation is not 
allowed on this special 
group. 
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Manifest Value Meaning 


NERR_UserInGroup 2236 The user already 
belongs to this group. 
NERR_UserNotInGroup 2237 The user does not 


belong to this group. 


NERR_InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 
e DosFreeSeg 
¢ DosFsCtl(NETTRANSACTION) 
¢ DosFsCtl(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 
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NetGroupSetUsers 
The NetGroupSetUsers (admin, DOS) function sets information about users who 
belong to a group. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetGroupSetUsers (servername, groupname, level, buf, buflen, entries) 


char far * servername; 
char far * groupname; 
short level; 
char far * buf; 
unsigned short buflen; 
unsigned short entries; 
where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
server. 


¢ groupname points to an ASCIIZ string specifying the group to set the users. 
¢ level specifies the level of detail (0) for the group_users_info data structure. 
¢ buf points to the group_users_info data structure. 

e buflen specifies the size (in bytes) of the buf memory area. 


¢ entries is the number of entries supplied in the buffer. 
Buffer Contents on Call (format for a single entry): 
Level 0 contains a struct group_users_info_0, repeated entries times. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR _ MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
NERR NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


- NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_GroupNotFound 


NERR_UserNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 


NERR_ACFFileIOFail 


Value 
2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2220 


yoHM | 


2226 


Z22) 


2228 


2229 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The group.does not 
exist. 


The user name cannot 
be found. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


An error was 
encountered in 
accessing the accounts 
database. 
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Manifest Value 


NERR_SpeGroupOp 2234 
NERR InvalidDatabase 2247 
NERR_InvalidComputer 2351 
NERR_CanNotGrowUASFile 2456 


Meaning 


This operation is not 
allowed on this special 
group. 

The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


It is not possible to 
grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCtlh(NETTRANSACTION) 

¢ DosFsCtlh(NULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize[-ERROR_DISK_FULL] 
¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 


¢ DosWrite. 


Remarks 


Trying to set the user membership of special group causes the NERR_SpeGroupOp 


error code to be returned. 


3-138 LAN Server Application Programmer’s Reference 


Handle Category 


NetHandleGetInfo (local, server)—See “NetHandleGetInfo” on page 3-140. 


NetHandleSetInfo (Jocal, server)—See “NetHandleSetInfo” on page 3-143. 


Description 
Two APIs are provided to get and set information on a per-handle basis. They are 
used with CHARDEV.H and NETCONS.H include files. 


Remote Serial Device and Named Pipe Handles 
The APIs provide per-handle control over the communications parameters for 
remote serial device and remote named pipe handles. These parameters are 
described in detail in “Requester Category” on page 3-208, under fields 
wki0_chartime and wki0_charcount. 


The values in the wksta_info_0 data structure are used as the default for each opened 
handle. The NetHandle APIs allow those parameters to be inspected and tuned on a 
per-handle basis. 


Serving Side of Named Pipd Handles 
The NetHandleGetInfo API is used to identify the user of a particular instance of a 
remote named pipe with multiple instances. If the named pipe has been opened 
locally, the error ERROR_INVALID_PARAMETER is returned. 


Data Structures 
struct handle_info_1 { 
unsigned long hdlil_chartime; 
unsigned short hdlil_charcount; 


} 
where: 


¢ hdlil_chartime is the amount of time (in milliseconds) the requester collects data 
to send to a shared serial device queue or a named pipe. 


¢ hdlil_charcount is the number of characters (in bytes) the requester stores before 
sending data to a serial device queue or a named pipe. 


struct handle info 2 { 
char far *  hd1li2_username; 
}; 


where: 
¢ hdli2_username is the user name of the user attached to a named pipe. It can be 


applied to a handle of the serving side of a valid remote named pipe only. 


Related Information 
For information on: 


¢ Creating multiple queues for a particular serial device—See “Serial Device 
Category” on page 3-238. 


¢ Data structure architecture—See Chapter 1, “Overview of OS/2 LAN Server 
API.” 


¢ Include files—See Appendix A, “Include Files.” 
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NetHandieGetinfo 


The NetHandleGetInfo (local, server) function retrieves handle-specific information. 
Syntax 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetHandleGetInfo(handle, level, buf, buflen, totalavail) 


unsigned short handle; 
short levels; 
char far * buf ; 

unsigned short buflen; 


unsigned short far *  totalavail; 
where: 


e handle is a unique identification of a communication device queue or a named 
pipe. 


¢ level specifies the level of detail (1 or 2) to be returned in the handle_info data 
structure. 


¢ buf points to the handle_info_I or handle_info_2 data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to the unsigned short integer indicating the number of bytes of 
information available. 


Serial Device and Named Pipe Handles Information (Level 1) 


Level 1 information is available for handles to remote serial devices and remote 
named pipes. If Jevel is 1 and the return code is.0 (NERR_Success), the buffer 
contains a handle_info_1 data structure. 


Named Pipe Handles Information (Level 2) 


Level 2 information is available for named pipe handles. If /evel is 2 and the return 
code is 0 (NERR_Success), the buffer contains a handle_info_2 data structure. 


Under DOS, only level one is valid, and only.on a handle to a remote named pipe. 


Return Codes 


Manifest. Value Meaning. 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS_DENIED 5 Administrative privilege is 
required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is not 
available. 

ERROR SHARING VIOLATION 32 A sharing violation 
occurred. 
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Manifest 
ERROR _NOT_SUPPORTED 


ERROR INVALID PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE_ DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR ServerNotStarted 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 


Value 
50 


87 


124 


234 


2102 


2104 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2351 


Meaning 


This request is not 
supported by the 
network. 


The specified parameter is 
invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the buffer 
is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The Server service has not 
been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling the 
workstation driver. 


The Requester service has 
not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


e DosDevIOCtl 
¢ DosFsRamSemClear 


¢ DosRamSemRequest 


¢ DosFsCthNETTRANSACTION) 


¢ DosFsCthNULLTRANSACT) 
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¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
* DosQNmPipelnfo | 

¢ DosSemClear 


e DosSemRequest. 


Remarks 
When level | is specified, the function has to be run on the requester. If the handle 
is not to a remote serial device or remote named pipe, the error 
ERROR_INVALID_PARAMETER is returned. 


When level 2 is specified, this function has to be run on the server. On level 2, it is 
used to identify the user of a particular instance of a remote named pipe with 
multiple instances. If the handle is not to a named pipe that a remote client 
currently has open, the error ERROR_INVALID_PARAMETER is returned. 
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NetHandleSetinfo 


Syntax 


Return Codes 


The NetHandleSetInfo (local, server) function sets handle-specific information. 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetHandleSetInfo(handle, level, buf, buflen, parmnum) 


unsigned short handle; 
short level; 
char far * buf; 
unsigned short buflen; 
unsigned short parmnum; 
where: 


¢ handle is a unique identification of a communication device queue or a named 
pipe. 

¢ level specifies the level of detail (1) to be returned in the handle_info data 
structure. 


¢ buf points to the handle_info_Idata structure or a single data structure 
component. 


© buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines whether buf contains a complete handle_info data structure 
or a single component. If parmnum is 0 and level is 1 then buf must contain a 
complete handle_info_1 or handle_info_2 data structure. Otherwise, parmnum 
must specify the ordinal position value for one of the following data structure 
components, as defined in CHARDEV.H as follows: 


Manifest Value Component 
HANDLE_SET_CHAR_ TIME 1 hdlil_chartime 
HANDLE_SET_CHAR_ COUNT 2 hdlil_charcount 


Serial Device and Named Pipe Handles Information (Level 1) 


For this function, only level 1 information is valid. Level 1 is valid for handles to 
remote serial devices and remote named pipes. 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS_DENIED 5 Administrative privilege is 
required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is not 
available. 

ERROR_SHARING VIOLATION 32 A sharing violation 
occurred. 
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Manifest 
ERROR_INVALID_PARAMETER 


ERROR _INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_ServerNotStarted 


NERR_BufTooSmall 


NERR_OS2loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 
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Value 


124 


234 


2102 


2104 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2351 


Meaning 


The specified parameter is 
invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the buffer 
is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The Server service has not 
been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling the 
workstation driver. 


The Requester service has 
not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosDeviOCtl 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCthNETTRANSACTION) 

¢ DosFsCthNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 
Remarks 
Because only level 1 is allowed in calling this function, it has to be run on a 
requester. If the handle is not to a remote serial device or remote named pipe, the 
error ERROR_INVALID_PARAMETER is returned. 


Under DOS, only level 1 is valid, and only on a handle to a remote named pipe. 
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Mailslot Category 


DosDeleteMailslot (local, DOS)—See “DosDeleteMailslot” on page 3-148. 
DosMailslotInfo (Jocal, DOS)—See “DosMailslotInfo” on page 3-149. 
DosMakeMailslot (/ocal, DOS)—See “DosMakeMailslot” on page 3-150. 
DosPeekMailslot (/ocal, DOS)—See “DosPeekMailslot” on page 3-151. 
DosReadMailslot (Jocal, DOS)—See “DosReadMailslot” on page 3-152. 
DosWriteMailslot (local, DOS)—See “DosWriteMailslot” on page 3-154. 


The functions in the Mailslot category provide one-way interprocess communication 
(IPC). They are used with the MAILSLOT.H and NETCONS.H include files. 


Description 
Through OS/2 LAN Requester/Server mailslots, data can be sent to either local or 
remote applications on the network. The Mailslot functions create and delete 
mailslots, retrieve information about a mailslot or a message in it, and write 
messages to mailslots. 


An application creates a mailslot on a local computer by calling the 
DosMakeMailslot function and assigning the mailslot a name in the format: 


\mailslot\name 


where: 


* name is a unique set of characters distinguishing the mailslot from other 
mailslots on the computer. 


The DosMakeMailslot function returns a handle to the mailslot. This handle can 
then be used with DosPeekMailslot to read a message in a mailslot, with 
DosReadMailslot to read and remove a message, with DosMailslotInfo to return 
information on a mailslot, and with DosDeleteMailslot to delete a mailslot. 


Any application can write messages to any mailslot on any computer on the network 
by calling the DosWriteMailslot function. DosWriteMailslot accepts mailslot names 
both in a local and remote format, as follows: 


Format Type 
\mailslot\name Local mailslot 
\\computername\mailslot\name Remote mailslot 


To write data to a mailslot on a remote computer, the name of the mailslot must 
also include a computer name. This requirement enables multiple remote computers 
to use the same mailslot name locally, but to have different names on the network 
(the computer name must be unique). 


An application can write the same message to all computers on the network that 


have a mailslot of a particular name. Only the second-class delivery is provided. By 
specifying an asterisk (*) for the computer name when calling NetWriteMailslot, 


3-146 LAN Server Application Programmer’s Reference 


\\*\mailslot\name 


sends the same message to the named mailslot on every computer in the sender’s 
primary domain that has the locally created mailslot. There is one limitation: 
requesters can only receive second-class messages of up to 400 bytes in length. 
Servers can receive first-class or second-class messages of any size. 


Two classes of messages—first-class and second-class—can be sent to mailslots. 


First-class messages, limited to mailslots on local computers and remote servers, are 
guaranteed — the message will be delivered or the sender will be notified. Ifa 
mailslot is full when a first-class message arrives, DosWriteMailslot waits until 
DosReadMailslot reads and removes a message from the mailslot or until the 
delivery time out expires (controlled by the timeout parameter in the 
DosWriteMailslot function). 


Second-class messages are simply sent; no return code informs the sender of an 
unsuccessful delivery. This simpler delivery system tends to make second-class 
messages faster than first-class messages. 


Messages are stored in the mailslot according to when they were received and the 
priority assigned them. Each message is assigned a priority from 0 (low) through 9 
(high) by way of the priority parameter of the DosWriteMailslot function. 

Generally, these priorities dictate the order in which messages are stored in a 
mailslot. High-priority messages are placed ahead of previously stored messages 
with the same or lower priority. However, since the OS/2 program is a multi-tasking 
operating system, this scheme cannot be guaranteed at any one time. 


Mailslot messages can be read only by the process that created the mailslot. 


The DosReadMailslot function reads and then removes the most current (next 
available) message. Since new messages may be placed in front of other messages due 
to priority, a process cannot be guaranteed that a message read by DosReadMailslot 
will be the same message seen earlier by DosPeekMailslot. 


DOS Considerations 
Under DOS, the functions can be executed on a local requester. Note that mailslots 
can only be read or deleted by the process that created them. Mailslots created by a 
process are deleted when that process ends. 


Related Information 


For information on interprocess communications (IPC), see “Named Pipe Category” 
on page 3-191. 
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DosDeleteMailslot 
The DosDeleteMailslot (local, DOS) function deletes a mailslot, discarding all 
messages, whether or not they have been read. 


Syntax 


#include <netcons.h> 
#include <mailslot.h> 


unsigned far pascal 
DosDeleteMailslot (handle) 
unsigned handle; 


where: 


¢ handle specifies the mailslot (by its handle) to delete. 


Return Codes 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 
ERROR INVALID HANDLE 6 The specified handle is not valid. 
NERR_NetNotStarted 2102 The redirector NETWKSTA.EXE 


has not been started. 


Remarks 
Mailslots enable applications to create and store messages during execution. 
Generally, these mailslots are deleted as the last step in the execution of a program. 


A mailslot can be deleted only by the application that created it. 


Related Information 
For information on: 


e Creating a mailslot—See “DosMakeMailslot” on page 3-150. 


¢ Obtaining information on the status of a mailslot—See “DosMailslotInfo” on 
page 3-149. 
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DosMailslotinfo 


Syntax 


Return Codes 


Related Information 


The DosMailslotInfo (local, DOS) function retrieves information about a particular 
mailslot. 


#include <netcons.h> 
#include <mailslot.h> 


unsigned far pascal 

DosMailslotInfo(handle, messagesize, mailslotsize, 
nextsize, nextpriority, msgcount) 

unsigned handle; 

unsigned short far * messagesize; 

unsigned short far * mailslotsize; 

unsigned short far * nextsize; 

unsigned short far * nextpriority; 

unsigned short far * msgcount; 


where: 
¢ handle specifies which mailslot (by its handle) to return information about. 


¢ messagesize points to an unsigned short integer indicating the maximum size (in 
bytes) of message that the mailslot can accept. 


¢ mailslotsize points to an unsigned short integer indicating the size (in bytes) of 
the mailslot. mailslotsize must equal or exceed messagesize. 


¢ nextsize points to an unsigned short integer indicating the size (in bytes) of the 
next message in the mailslot. If 0, no message is available. 


¢ nextpriority points to an unsigned short integer indicating the priority (0 theough 
9) of the next message in the mailslot (undefined if nextsize is 0). 


¢ msgcount points to an unsigned short integer indicating the number of messages 
the mailslot contains. 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 
ERROR_INVALID_HANDLE 6 The specified handle is not valid. 
NERR_NetNotStarted 2102 The redirector NETWKSTA.EXE 


has not been started. 


For information on: 


e Creating (and obtaining the handle for) a mailslot—See “DosMakeMailslot” on 
page 3-150. 


e Writing a message to a mailslot—See “DosWriteMailslot” on page 3-154. 


¢ Retrieving the most current message in a mailslot—See “DosReadMailslot” on 
page 3-152. 
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DosMakeMailslot 
The DosMakeMailslot (local, DOS) function creates a mailslot and returns its 
handle. 


Syntax 


#include <netcons.h> 
#include <mailslot.h> 


unsigned far pascal 

DosMakeMailslot(name, messagesize, mailslotsize, handle) 
char far * name; 

unsigned short messagesize; 

unsigned short mailslotsize; 

unsigned far * handle; 


where: 


* name points to an ASCIIZ string assigning a name to the mailslot. Use the 
format \mailslot\name. 


¢ messagesize specifies the maximum message size (in bytes) that the mailslot can 
accept. Generally, mailslots cannot accept messages larger than 65475 bytes. 


¢ mailslotsize specifies the size (in bytes) of the mailslot. mailslotsize must equal or 
exceed messagesize. 


¢ handle points to an unsigned integer that is the returned handle for the mailslot. 


Return Codes 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 

ERROR_PATH_NOT_FOUND 3 The path was not found. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is not 
available. 

ERROR_INVALID_PARAMETER 87 The specified parameter is 
invalid. 

NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has not 


been started. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocShrSeg 
¢ DosExitList. 
Remarks 


Mailslot names must be unique; no two mailslots on any one computer can have the 
same name. 


Mailslot handles cannot be passed to other processes by way of the OS/2 
DosExecPgm function; however, mailslot handles can be shared among threads in a 
single process. Thus, multiple threads can use the same handle to read or write data 
to the mailslot. 


3-150 LAN Server Application Programmer’s Reference 


DosPeekMailslot 


Syntax 


Return Codes 


Remarks 


Related Information 


The DosPeekMailslot (local, DOS) function reads the next available message in a 
mailslot without removing it. 


#include <netcons.h> 
#include <mailslot.h> 


unsigned far pascal 

DosPeekMailslot(handle, buf, bytesread, nextsize, nextpriority) 
unsigned handle; 

char far * buf; 

unsigned short far * bytesread; 

unsigned short far * nextsize; 

unsigned short far * nextpriority; 


where: 
e handle specifies which mailslot (by its handle) is to be read. 


e buf points to the returned message. buf must be as large as the messagesize 
parameter passed to the DosMakeMailslot function. 


¢ bytesread points to an unsigned short integer indicating the size (in bytes) of the 
returned message. If no message is available, bytesread is 0. 


¢ nextsize points to an unsigned short integer indicating the size (in bytes) of the 
next message in the mailslot. If the mailslot contains no other message, nextsize 
is 0. 


e nextpriority points to an unsigned short integer indicating the priority of the next 
message in the mailslot (undefined if nextsize is 0). 


Manifest Value Meaning 

NERR_ SUCCESS 0 No errors were encountered. 
ERROR_INVALID_ HANDLE = 6 The specified handle is not valid. 
ERROR_BROKEN PIPE 109 Write on pipe with no reader. 
NERR_NetNotStarted 2102 The redirector NETWKSTA.EXE 


has not been started. 


Other error return codes may be returned from the DosSemRequest function. 


If a higher-priority message arrives, there is no guarantee that a message previously 
read by the DosPeekMailslot function will be the same message read by a 
subsequent call to the DosReadMailslot function. 


For information on: 
e Reading and removing a message—See “DosReadMailslot” on page 3-152. 


e Writing a message to a mailslot—See “DosWriteMaiislot” on page 3-154. 
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DosReadMailslot 


The DosReadMailslot (local, DOS) function reads, then removes the next available 
message of a mailslot. 


Syntax 


#include <netcons.h> 
#include <mailslot.h> 


unsigned far pascal 

DosReadMailslot(handle, buf, bytesread, nextsize, 
nextpriority, timeout) 

unsigned handle; 

char far * buf; 

unsigned short far * bytesread; 

unsigned short far * nextsize; 

unsigned short far * nextpriority; 

Tong timeout; 


where: 
¢ handle specifies which mailslot (by its handle) to read from. 


¢ buf points to the returned message. buf must be as large as the messagesize 
parameter passed to the DosMakeMailslot function. 


¢ bytesread points to an unsigned short integer indicating the size (in bytes) of the 
returned message. If 0, no message is available. 


¢ nextsize points to an unsigned short integer indicating the size (in bytes) of the 
next message in the mailslot. If 0, the mailslot contains no more messages. 


¢ nextpriority points to an unsigned short integer indicating the priority (0-9) of 
the next message (undefined if nextsize is 0.) 


¢ timeout points to an unsigned short integer indicating the number of milliseconds 
to wait if a message is not available immediately. If 0, DosReadMailslot does 
not wait; if -1, DosReadMailslot waits indefinitely. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were encountered. 
ERROR_INVALID HANDLE 6 The specified handle is not valid. 
ERROR_INTERRUPT 95 A system call has been interrupted. 
ERROR_BROKEN PIPE 109 Write on pipe with no reader. 
ERROR_SEM_TIMEOUT 121 A time out happened from the 
semaphore API functions. 
NERR_NetNotStarted 2102 The redirector NETWKSTA.EXE 


has not been started. 


Other error return codes may be returned from the DosSemRequest function. 
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Remarks 
Messages are stored in a mailslot based on their priority (0-9). An incoming 
message with a higher priority may be stored ahead of a previously stored message 
-with the same or lower priority. The message read and removed by 
DosReadMailslot is always the next available. 


Related Information 
For information on: 


¢ Reading a message without removing it—See “DosPeekMailslot” on page 3-151. 


e Writing a message to a mailslot—See “DosWriteMailslot” on page 3-154. 
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DosWriteMailslot 


The DosWriteMailslot (local, DOS) function writes a message to a particular 
mailslot. 


Syntax 


#include <netcons.h> 
#include <mailslot.h> 


unsigned far pascal 

DosWriteMailslot(name, message, size, priority, class, timeout) 
char far * name; 

char far * message; 

unsigned short size; 

unsigned short priority; 

unsigned short class; 

long timeout; 


where: 


© name points to an ASCIIZ string containing the name of the mailslot to which 
the message is to be written. For a local mailslot, use the format \mailslot\name. 
Use the \\computername\mailslot\name format for a remote mailslot. Use 
\\*\mailslot\name for all mailslots with the same name, but on different 
computers in the primary domain. 


¢ message points to an ASCIIZ string containing the message to be written to the 
mailslot. 


e size specifies the size (in bytes) of message. 


¢ priority assigns a priority (0 through 9) to the message. High-priority messages 
are generally placed ahead of previously stored messages with lower priority. 


¢ class specifies the class of mail service to be provided. 


— First-class mail (class is 1) forces DosWriteMailslot to wait until a mailslot 
has enough room to accept message or until timeout expires. First-class mail 
can be delivered only to remote servers or local computers. 


— Second-class mail (class is 2) causes DosWriteMailslot to fail if there is not 
enough room to write message in the mailslot. Second-class mail can be 
delivered to requesters and servers. 


¢ timeout specifies the number of milliseconds to attempt writing a message to a 
mailslot. If 0, DosWriteMailslot attempts to write the message only once. If -1, 
DosWriteMailslot attempts to write a message to a mailslot for an indefinite 


time. 
Return Codes 

Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 

ERROR _PATH_NOT_FOUND 3 The path was not found. 

ERROR_ACCESS_DENIED 5 Administrative privilege is 
required. 

ERROR _NOT_ENOUGH_MEMORY 8 Sufficient memory is not 
available. 
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Manifest 
ERROR_BAD_FORMAT 
ERROR_NOT_SUPPORTED 


ERROR_NETWORK_BUSY 
ERROR_BAD_NET_ NAME 


ERROR_INVALID_PARAMETER 


ERROR_INTERRUPT 


ERROR_BROKEN_ PIPE 


ERROR_BUFFER_OVERFLOW 


ERROR_SEM_TIMEOUT 


ERROR_INVALID_NAME 


ERROR_INVALID_LEVEL 


ERROR MORE DATA 


NERR _NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 
NERR_BadTransactConfig 


NERR_InvalidComputer 


Value 
11 
50 


54 
67 


87 


95 


109 


111 


121 


123 


124 


234 


2102 


2104 


2123 


2134 


2138 


2139 


2140 
2141 


2351 
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Meaning 
The format is not valid. 


This request is not supported 
by the network. 


The network is busy. 


This network name cannot be 
found. 


The specified parameter is 
invalid. 


A system call has been 
interrupted. 


Write on pipe with no reader. 


The buffer passed to system 
call is too small to hold return 
data. 


A time out happened from the 
semaphore API functions. 


There is an incorrect character 
or incorrectly formed file 
system name. 


The Level parameter is invalid. 


Additional data is available, 
but the buffer is too small. 


The redirector 
NETWKSTA.EXE has not 
been started. 


An internal error occurred—the 
network cannot access a shared 
memory segment. 


The buffer is too small for 
fixed-length data. 


An internal error occurred 
when calling the workstation 
driver. 


The Requester service has not 
been started. 


The requested information is 
not available. 


An internal error has occurred. 


The server is not configured for 
transactions. 


The specified computer name is 
invalid. 
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Other error return codes may be returned from the following OS/2 functions: . 
¢ DosAllocSeg 
¢ DosDevIOCtl 
¢ DosFSCtl 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCthNETTRANSACTION) 
¢ DosFsCth(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear 
¢ DosSemRequest 
¢ redir.GetBiosInfo[-ERROR_NO MORE FILES] 
¢ redir.NETTRANSACTION_1 
e redir.NIOCBIOSOPEN. 

Remarks. 
To send a message to all computers on the primary domain that have a local 


mailslot with the same name, an application must pass the name parameter 
\\*\mailslot\name and the class parameter 2 to DosWriteMailslot. 


Second-class messages must be 400 bytes or smaller when written to remote 
requesters; they can be any size when written to local computers or remote servers. 


Related Information 
For information on: 


e Creating a mailslot—See “DosMakeMailslot” on page 3-150. 
e Reading a message—See “DosReadMailslot” on page 3-152. 


3-156 LAN Server Application Programmer’s Reference 


Message Category 


Description 


NetMessageBufferSend (admin, DOS)—See “NetMessageBufferSend” on page 3-161. 
NetMessageFileSend (admin, DOS)—See “NetMessageFileSend” on page 3-164. 
NetMessageLogFileGet (admin, DOS)—See “NetMessageLogFileGet” on page 3-168. 
NetMessageLogFileSet (admin, DOS)}—See “NetMessageLogFileSet” on page 3-170. 
NetMessageNameAdd (admin, DOS)—See “NetMessageNameAdd” on page 3-173. 
NetMessageNameDel (admin, DOS)—See “NetMessageNameDel” on page 3-176. 


NetMessageNameEnum (admin, DOS)—See “NetMessageNameEnum” on 
page 3-179. 


NetMessageNameF wd (admin)—See “NetMessageNameFwd” on page 3-182. 


NetMessageNameGetInfo (admin, DOS)—See “NetMessageNameGetInfo” on 
page 3-185. 


NetMessageNameUnFwd (admin)—See “NetMessageNameUnFwd” on page 3-188. 


The functions in the Message category are used to send, log, and forward messages. 
The administrator can execute these functions remotely. They are used with the 
MESSAGE.H and NETCONS.H include files. 


A message is any file or buffer of data sent to a messaging name on the network. To 
receive a message, a user or application must register a messaging name (using the 
NetMessageNameAdd function) in the message name table of a computer. A 
message name table contains a list of registered messaging names permitted to 
receive messages and a list of users and applications to which a message can be 
forwarded. Messaging names must be case-sensitive and unique on the physical 
network, not just the domain. 


Messaging names are deleted from the message name table using the 
NetMessageNameDel function. 


To list all the names stored in the table, an application can call the 
NetMessageNameEnum function. For information on a particular user in the table, 
an application can call the NetMessageNameGetInfo function. 


All of the Message functions except NetMessageBufferSend and 
NetMessageFileSend require that the local computer be running the messenger 
service. The NetMessageBufferSend and the NetMessageFileSend functions only 
require that the remote computer receiving a message be running the messenger 
service. 


To send a message to a user, an application can call either the NetMessageFileSend 


function (to send a file) or tne NetBufferSend function (to send a buffer of 
information). 
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All messages sent to a user on a particular computer can be forwarded to another 
user on a different computer using the NetMessageNameFwd function. The 
NetMessageNameUnFwd function is used to end message forwarding. 


Applications can also send broadcast messages to all users on the network registered 
in the message name table of each computer by passing the name parameter for the 
NetMessageFileSend function or NetMessageBufferSend function as an asterisk (*). 


To send to all users on a particular domain, pass the name parameter as “domain*.” 


Users can receive messages in one of two ways (or both at the same time): 
¢ The received message is logged to a message log file and looked at later. 


e The message is displayed as a popup message on the screen. To receive a 
popup, the netpopup service must be started. For more information on starting 
the netpopup service, see “Service Category” on page 3-298. 


If an application turns logging on (using NetMessageLogFileSet), all messages 
received for a particular user are stored in a message log file. The 
NetMessageLogFileGet function returns the name of a message log file of a 
requester or server and indicates whether or not message logging is enabled. The 
default message log file is \IBMLAN\LOGS\MESSAGES.LOG. 

The message log file contains a message in the following format: 


e A header specifying who sent the message, who received the message, and when 
(time and date) the message was received 


e A blank line 

¢ The contents of the message 

¢ A blank line 

e A line containing four asterisks (*) 
¢ A blank line. 


For example, the following is the contents of the message log file containing two 
messages: 


Message from KRISCA to AJSCHEL on Aug 04, 1990, 14:05:20 
Hello, this is a BUFFER message. 

kk 

Message from KRISCA to AJSCHEL on Aug 04, 1990, 14:11:48 


Hello, this is a FILE message. 


Note: Any process opening the message log file must open it in only the read-only 
deny-none mode; otherwise, the messenger service fails when trying to log 
incoming messages. 
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DOS Considerations 
Under DOS, the functions can be executed only on a local requester. Attempting to 
execute the functions on a remote server returns ERROR_NOT_SUPPORTED. 


Messages cannot be forwarded, unforwarded, or logged under DOS. 


By default, the DOS LAN Requester accepts only two names in the message name 
table—the name of the requester and of the user. To define more names, edit the 
DOSLAN INI file and change the value of the nmsg parameter for the messenger 
component. For more information on the DOSLAN_INI file, see the DOS LAN 
Requester User's Guide. 


The maximum size of a message under DOS is 64KB. 


Data Structures 
The NetMessageNameEnum and NetMessageNameGetInfo functions can accept or 
return data at a level 0 or level 1 of detail using the following data structures. None 
of the other Message functions use a data structure. 


Message Information (Level 0) 


struct msg_info_0 { 
char msgi@_name[CNLEN+1]; 
}; 


where: 


¢ msgi0_name is an ASCIIZ string specifying which messaging name to send the 
message. 


Message Information (Level 1) 


struct msg_info_1 { 


char msgii_name[CNLEN+1]; 
char msgil_forward_flag; 
unsigned char msgil_padl; 
char msgil_forward[CNLEN+1] ; 
hs 
where: 


¢ msgil_name is an ASCIIZ string specifying which messaging name to send the 
message. 


¢ msgil_forward_flag specifies whether messages will be sent to a user or 
application on the local computer, or forwarded to a user or application on a 
remote computer. msgil_forward_flag can be defined as follows: 


Bit Manifest Meaning 

0-1 MSGNAME_NOT_FORWARDED Reserved; must be 0. 

2 MSGNAME_FORWARDED _TO If 1, specifies a user 
name on a remote 
computer. 

3 MSGNAME_ NOT FORWARDED Reserved; must be 0. 
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Bit Manifest Meaning 


4 MSGNAME_ FORWARDED FROM If 1, specifies a user 
name on the local 
computer. 

5-7 MSGNAME_NOT_FORWARDED Reserved; must be 0. 


¢ msgil_pad] WORD-aligns the data structure components. 


¢ mysgil_forward is an ASCIIZ string specifying the user name to which the 
message will be sent, if messages are to be forwarded. 


Related Information 
For information on starting services and the messenger service see “Service 
Category” on page 3-298. 


3-160 LAN Server Application Programmer’s Reference 


NetMessageBufferSend 


Syntax 


Return Codes 


The NetMessageBufferSend (admin, DOS) function sends a buffer of information to 
a registered messaging name. 


#include <netcons.h> 
#include <message. h> 


unsigned far pascal 

NetMessageBufferSend (servername, name, buf, buflen) 
const char far * servername; 

char far * name; 

char far * buf 

unsigned short  buflen; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ name points to an ASCIIZ string indicating the name of the registered user or 
application to receive the message. To broadcast a message to all requesters on 
the LAN, have name point to an asterisk (*). To broadcast a message to a 
domain, have name point to a domain name, followed by an asterisk. 


e buf points to the message. 


e buflen specifies the size (in bytes) of the buf memory area. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were . 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_REM_NOT_LIST 51 This remote computer 
is not listening. 
ERROR_INVALID PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 
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Manifest 
NERR_NoNetworkResource 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_NetworkError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_NoComputerName 


NERR_NameNotFound 


NERR _ AlreadyExists 


NERR_TooManyNames 


NERR_PausedRemote 


NERR_BadReceive 


NERR_NotLocalName 


NERR_TruncatedBroadcast 


NERR_DuplicateName 
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Value 
2105 


2123 


2127 


2134 


2136 


2138 


2139 


2140 


2141 


2270 


2213 


2276 


VIA 


2281 


2282 


2285 


2289 


2297 


Meaning 


A network resource 
shortage occurred. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


A computer name has 
not been configured. 


The message alias 
cannot be found on the 
local area network. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


The message has been 
sent but the reception 
is currently paused. 


The message was sent 
but not received. 


The name is not on the 
local computer. 


The broadcast message 
was truncated. 


A duplicate message 
alias exists on the local 
area network. 


Manifest Value Meaning 


NERR _ InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
© DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCtlh(NULLTRANSACT) 
¢ DosFsCti(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear 


© DosMailslot. 


Remarks 

For broadcast messages (name points to “*” or “domain (*)”), the message can be 
no longer than 128 characters (and is not guaranteed to be delivered). For messages 
sent to all computers in a domain, the limit is 128 bytes. Otherwise, the message can 
be any length, provided it does not exceed the maximum receivable message size for 
that computer, which is set with the sizmessbuf parameter in IBMLAN.INI. (The 
sizmessbuf parameter in IBMLAN.INI cannot define a value larger than 64KB.) 
The default value of sizmessbuf on any server is 4K B. Note that the total size of 
sizmessbuf may be divided between different messages in its heap (if messages are 
arriving at the same time), reducing the actual size of any one message that can be 
received. And, note that the sizmessbuf parameter can accept only limited values. 
For more information on the IBMLAN._INI file, see the JBM Operating System/2 
Local Area Network Server Version 1.2 Network Administrator’s Guide. 


NetMessageBufferSend does not require the messenger service to be started on a 
local computer. The remote computer needs the messenger service to be started. 


DOS Considerations 
Under DOS, the name parameter cannot point to the name of the local requester or 
to the user currently logged onto that requester. 


Related Information 
For information on: 


e Adding a user to a message table—See “NetMessageNameAdd” on page 3-173. 
e The messenger service—See “Service Category” on page 3-298. 
e Sending a message file to a user—See “NetMessageFileSend” on page 3-164. 


¢ Setting the sizmessbuf parameter of a server in IBMLAN.INI—See the JBM 
Operating System/2 Local Area Network Server Version 1.2 Network 
Administrator's Guide. 
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NetMessageFileSend 
The NetMessageFileSend (admin, DOS) function sends a file to a registered 
messaging name. 


Syntax 


#include <netcons.h> 
#include <message.h> 


unsigned far pascal 
NetMessageFileSend (servername, name, filespec) 
const char far * servername; 


char far * name; 
char far * filespec; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies the local 
computer. 


¢ name points to an ASCIIZ string specifying the registered user or application to 
receive the file. To broadcast a file to all registered users and applications, pass 
the name parameter as a pointer to the ASCII string “*.” To broadcast a 
message to a domain, have name point to a domain name, followed by an 
asterisk (*). 


e filespec points to an ASCIIZ string [d:][\ path\]file[.ext] specifying the path 
name of a file to send. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED > Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_REM_NOT_LIST 51 This remote computer 
is not listening. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 
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Manifest 
NERR_NoNetworkResource 


NERR_BufTooSmail 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR _NetworkError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_NoComputerName 


NERR_NameNotFound 


NERR AlreadyExists 


NERR_TooManyNames 


NERR _PausedRemote 


NERR _BadReceive 


NERR_NotLocalName 


NERR_TruncatedBroadcast 


NERR_FileError 


Value 
2105 


2123 


2127 


2134 


2136 


2138 


2139 


2140 


2141 


2270 


2273 


2276 


2201 


2281 


2282 


2285 


2289 


2290 


Meaning 


A network resource 
shortage occurred. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


A computer name has 
not been configured. 


The message alias 
cannot be found on the 
local area network. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


The message has been 
sent but the reception 
is currently paused. 


The message was sent 
but not received. 


The name is not on the 
local computer. 


The broadcast message 
was truncated. 


An error occurred in 
reading the message 
file. 
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Manifest Value Meaning 


NERR InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCth(NETTRANSACTION) 

¢ DosFsCthKNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen 

¢ DosRead 

¢ DosSemClear 


e¢ DosWriteMailslot. 


Remarks 

For broadcast messages to the physical network (name points to “*” or “domain 
(*)”), the message can be no longer than 128 characters (and is not guaranteed to be 
delivered). For messages sent to all computers in a domain, the limit is 128 bytes. 
Otherwise, the message can be any length, provided it does not exceed the maximum 
receivable message size for that computer, which is set with the sizmessbuf parameter 
in IBMLAN.INI. (The IBMLAN.INI sizmessbuf parameter cannot define a value 
larger than 64KB.) The default value of sizmessbuf on any server is 4KB. Note that 
the total size of sizmessbuf may be divided between different messages in its heap (if 
messages are arriving at the same time), reducing the actual size of any one message 
that can be received. And, note that the sizmessbuf parameter can also accept only 
limited values. For more information on the IBMLAN_INI file, see the JBM 
Operating System/2 Local Area Network Server Version 1.2 Network Administrator's 
Guide. 


NetMessageFileSend does not require the messenger service to be started on a local 
computer. 


If any special characters (for example, Ctrl + Z) are sent in a file, no information is 
omitted. 


DOS Considerations 


Under DOS, the name parameter cannot point to the name of the local requester or 
to the user currently logged on to that requester. 
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Related Information 
For information on: 


¢ The messenger service—See “Service Category” on page 3-298. 


¢ Sending a buffer of information to a user—See “NetMessageBufferSend” on 
page 3-161. 


e Setting the sizmessbuf parameter of a server in IBMLAN.INI-—See the JBM 
Operating System/2 Local Area Network Server Version 1.2 Network 
Administrator's Guide. 
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NetMessageLogFileGet 


The NetMessageLogFileGet (admin, DOS) function retrieves the name of the 


message log file and the current logging status (on or off). 


Syntax 
#include <netcons.h> 
#include <message. h> 


unsigned far pascal 


NetMessageLogFileGet (servername, buf, buflen, on) 


const char far * servername; 


char far * buf 
unsigned short buflen; 
short far * on; 
where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


computer. 


¢ buf points to the returned message log file path name. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


* on points to a short integer specifying whether or not logging is enabled. If zero, 
message logging is disabled. If non-zero, message logging is enabled. 


Return Codes 
Manifest 
NERR_SUCCESS 
ERROR_ACCESS_ DENIED 
ERROR_NOT_ENOUGH_ MEMORY 
ERROR_INVALID_ PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_BufTooSmall 
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Value 


0 


87 


124 


234 


2102 


2104 


2123 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


Manifest Value Meaning 


NERR_RemoteErr 2127 A remote API error 


has occurred. 


NERR_OS2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR_MsgNotStarted 2284 The messenger service 


has not been started. 


NERR InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 
DosFsCtl(NETTRANSACTION) 
DosFsCthNULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 


DosSemClear. 


NetMessageLogFileGet requires that the messenger service be started. 


Related Information 


For information on: 


The messenger service—See “Service Category” on page 3-298. 


Modifying the name and the logging status of the message log file—See 
“NetMessageLogFileSet” on page 3-170. 
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NetMessageLogFileSet 
The NetMessageLogFileSet (admin, DOS) function specifies a file to log messages 
received by registered users and enables or disables logging. 


Syntax 


#include <netcons.h> 
#include <message.h> 


unsigned far pascal 

NetMessageLogFileSet (servername, filespec, on) 
const char far * servername; 

char far * filespec; 

unsigned short on; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ filespec points to an ASCIIZ string specifying the path name of the device 
(LPTn or COMn) or file to which the messages are logged. 


If filespec is passed as a NULL pointer, the name of the current message log file 
does not change. If filespec points to a NULL string (””), no message file will be 
used; in this case, the value of on must be 0. 


If filespec points to a relative path, the path must be relative to the 
IBMLAN\LOGS directory. All other path names must be fully qualified. If no 
file name extension is provided, the .LOG file extension is appended. 


¢ on isa short integer specifying whether or not logging is enabled. If zero, 
message logging is disabled. If non-zero, message logging is enabled. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR _INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_NAME 123 There is an incorrect 


character or incorrectly 
formed file system 


name. 

ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 

ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
ERROR _ FILENAME EXCED_ RANGE 


ERROR_VIO_DETACHED 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RedirectedPath 


NERR_BufTooSmall 
NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_MsgNotStarted 


NERR InvalidDevice 


NERR_WriteFault 


NERR InvalidComputer 


NERR _ CantType 


Value 
206 


465 


2102 


2104 


2117 


2123 


2127 


2134 


2138 


2139 


2140 


2141 


2284 


2294 


2295 


2351 


2357 


Meaning 


The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 


The console is not 
available for logging. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The operation is 
invalid on a redirected 
device. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The messenger service 
has not been started. 
This is an invalid 
device. 


A write fault has 
occurred. 


The specified computer 
name is invalid. 


The type of input 
cannot be determined. 
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Other error return codes may be: returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCth(NETTRANSACTION) 

¢ DosFsCth(NULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen 

¢ DosQHandType 

¢ DosSemClear 

¢ DosWrite 

¢ redir.GetNetInitPath. 


Remarks 
NetMessageLogFileSet requires that the messenger service be started. 


Related Information. 
For information on: 
¢ The messenger service—See “Service Category” on page 3-298. 


¢ Retrieving the name and logging status of the message log file—See 
“NetMessageLogFileGet” on page 3-168. 
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NetMessageNameAdd 


Syntax 


Return Codes 


The NetMessageNameAdd (admin, DOS) function registers a name in the message 
name table. 


#include <netcons.h> 
#include <message. h> 


unsigned far pascal 
NetMessageNameAdd(servername, name, fwd_action) 
const char far * servername; 


char far * name ; 
short fwd_action; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ name points to an ASCIIZ string specifying a name to add to the message name 
table. 


e fwd_action specifies the action to take if name is already forwarded. If 
fwd_action is non-zero, the name is added to the message name table; a zero 
value causes an error to be returned if the name has already been forwarded. 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR _ ACCESS DENIED 5 Administrative 
privilege is required. 

ERROR NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 

ERROR REM _NOT_LIST 51 This remote computer 
is not listening. 

ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 

ERROR _INVALID_LEVEL 124 The Level parameter is 
invalid. 

NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 


not been started. 


NERR ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_NoNetworkResource 2105 A network resource 
shortage occurred. 
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Manifest 
NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2loctiError 


NERR_NetworkError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_NameNotFound 


NERR_AlreadyForwarded 


NERR_AddForwarded 


NERR_AlreadyExists 


NERR_TooManyNames 


NERR_MsgNotStarted 


NERR_DuplicateName 


NERR_DeleteLater 


NERR_InvalidComputer 
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Value 
2123 


2127 


2134 


2136 


2138 


2139 


2140 


2141 


2273 


2274 


2275 


2276 


2277 


2284 


2297 


2298 


2351 


Meaning 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has © 
occurred. 


The server is not 
configured for 
transactions. 


The message alias 
cannot be found on the 
local area network. 


This message alias has 
already been 
forwarded. 


This message alias has 
been added but is still 
forwarded. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


The messenger service 
has not been started. 


A duplicate message 
alias exists on the local 
area network. 


This message alias will 
be deleted later. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFSRamSemClear 
¢ DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCthNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE NOT_FOUND] 


¢ DosSemClear. 


Related Information 
For information on: 


e Deleting a user name from a message name table—See “NetMessageNameDel” 
on page 3-176. 


e Forwarding messages—See “NetMessageNameFwd” on page 3-182. 


e Listing the user names in a message name table—See “NetMessageNameEnum” 
on page 3-179. 


e Messenger service—See “Service Category” on page 3-298. 
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NetMessageNameDel 
The NetMessageNameDel (admin, DOS) function deletes a name from a message 
name table. 


Syntax 


#include <netcons.h> 
#include <message.h> 


unsigned far pascal 
NetMessageNameDel (servername, name, fwd_action) 
const char far * servername; 


char far * name ; 
short fwd_action; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ name points to an ASCIIZ string specifying the name to be removed. 


e fwd_action specifies the action to take if the messages for name are being 
forwarded to another name. If fwd_action is non-zero, the forwarded name is 
deleted. A zero value prevents the name from being deleted. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_REM_NOT_LIST 51 This remote computer 
is not listening. 
ERROR_ INVALID PARAMETER 87 The specified 
parameter is invalid. 
ERROR _INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_NoNetworkResource 2105 A network resource 
shortage occurred. 
NERR_BufTooSmall 2123 The buffer is too small 


for fixed-length data. 
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Manifest 
NERR_RemoteErr 


NERR_OS2IoctlError 


NERR _NetworkError 
NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR _BadTransactConfig 


NERR_NameNotFound 


NERR _AlreadyForwarded 


NERR_AlreadyExists 


NERR_TooManyNames 


NERR_DelComputerName 


NERR_NameInUse 


NERR_MsgNotStarted 


NERR NotLocalName 


NERR_DuplicateName 


NERR _DeleteLater 


Value 
2127 


2134 


2136 
2138 


2139 


2140 


2141 


2273 


2274 


2276 


2277 


2278 


2283 


2284 
2285 


2297 


2298 


Meaning 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The message alias 
cannot be found on the 
local area network. 


This message alias has 
already been 
forwarded. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


The computer name 
cannot be deleted. 


The message alias is 
currently in use—try 
again later. 


The messenger service 
has not been started. 


The name is not on the 
local computer. 


A duplicate message 
alias exists on the local 
area network. 


This message alias will 
be deleted later. 
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Manifest Value Meaning 


NERR_IncompleteDel 2299 The message alias was 
not successfully deleted 
from all networks. 


NERR_InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCtl(NETTRANSACTION) 
¢ DosFsCth(KNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 


Remarks 
NetMessageNameDel requires that the messenger service be started. 


Related Information 
For information on: 


e Adding a name to a message name table—See “NetMessageNameAdd” on 
page 3-173. 


e Listing the names in a particular message name table—See 
“NetMessageNameEnum” on page 3-179. 


e The messenger service—See “Service Category” on page 3-298. 
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NetMessageNameEnum 


Syntax 


Return Codes 


The NetMessageNameEnum (admin, DOS) function lists the name entries in a 
message name table. 


#include <netcons.h> 
#include <message. h> 


unsigned far pascal 
NetMessageNameEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


const char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


e level specifies the level of detail (0 or 1) to be returned in the msg_info data 
structure. 


¢ buf points to the msg_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR _ INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest Value Meaning 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 

NERR_ShareMem 2104 ‘An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteErr 2127 A remote API error 
has occurred. 
NERR_OSZ2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR _BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR_MsgNotStarted 2284 The messenger service 


has not been started. 


NERR_InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
* DosFsCtlh(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 


Remarks 
NetMessageNameEnum requires that the messenger service be started. 
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Related Information 
For information on: 


e Adding a name to a message name table—See “NetMessageNameAdd” on 
page 3-173. 


¢ Deleting a name from a message name table—See “NetMessageNameDel” on 
page 3-176. 


e The messenger service—See “Service Category” on page 3-298. 


¢ Retrieving information about a user’s message account—See 
“NetMessageNameGetInfo” on page 3-185. 
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NetMessageNameFwd 
The NetMessageNameFwd (admin) function modifies the message name table to 
forward messages to another messaging name. 


Syntax 
#include <netcons.h> 
#include <message. h> 


unsigned far pascal 

NetMessageNameFwd(servername, name, forwardname, del for) 
const char far * servername; 

const char far * name; 


char far * forwardname; 
short delfor; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


* name points to an ASCIIZ string specifying the name receiving messages. 


¢ forwardname points to an ASCIIZ string specifying the name to receive name’s 
forwarded messages. 


¢ delfor specifies the action to take if name forwards messages to another name. If 
non-zero, then any previous forwarded user name is deleted; if 0, it is not deleted 
and an error is returned. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_REM_NOT_LIST 51 This remote computer 
is not listening. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_NoNetworkResource 2105 A network resource 
shortage occurred. 
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Manifest 
NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_NetworkError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _ InternalError 


NERR_BadTransactConfig 


NERR_ NameNotFound 


NERR _ AlreadyForwarded 


NERR AlreadyExists 


NERR_TooManyNames 


NERR_LocalForward 


NERR_NamelInUse 


NERR_MsgNotStarted 


NERR_NotLocalName 


NERR_RemoteFull 


Value 
2123 


2127 


2134 


2136 


2138 


2139 


2140 


2141 


2273 


2274 


2276 


2211 


2219 


2283 


2284 


2285 


2287 


Meaning 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The message alias 
cannot be found on the 
local area network. 


This message alias has 
already been 
forwarded. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


Messages cannot be 
forwarded back to the 
same workstation. 


The message alias is 
currently in use—try 
again later. 


The messenger service 
has not been started. 


The name is not on the 
local computer. 


The message alias table 
on the remote station 
is full. 
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Manifest Value Meaning 
NERR_DuplicateName 2297 A duplicate message 


alias exists on the local 
area network. 


NERR_DeleteLater 2298 This message alias will 


be deleted later. 


NERR_MultipleNets 2300 This operation is not 


supported on machines 
with multiple 
networks. 


NERR InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 

DosFsCth(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


NetMessageNameFwd requires that the messenger service be started. 


Related Information 


For information on: 


Listing the entries in the message name table of a server—See 
“NetMessageNameEnum” on page 3-179. 


The messenger service—See “Service Category” on page 3-298. 


Setting the sizmessbuf parameter for a server in IBMLAN.INI—See the IBM 
Operating System/2 Local Area Network Server Version 1.2 Network 
Administrator's Guide. 


Stopping forwarding of a user’s messages—See “NetMessageNameUnFwd” on 
page 3-188. 
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NetMessageNameGetinfo 


Syntax 


Return Codes 


The NetMessageNameGetInfo (admin, DOS) function retrieves information about a 
user’s entry in the message name table. 


#include <netcons.h> 
#include <message. h> 


unsigned far pascal 


’ NetMessageNameGetInfo(servername, name, level, buf, 


buflen, totalavail) 


const char far * servername; 
const char far * name ; 

short level; 
char far * buf ; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


* name points to an ASCIIZ string specifying the name of the user of interest. 


¢ level specifies the level of detail (0 or 1) requested for the returned msg_info data 
structure. 


¢ buf points to the msg_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_MsgNotStarted 


NERR_NotLocalName 


NERR_InvalidComputer 


Value 
2104 


2123 


2127 


2134 


2138 


2139 


2140 


2141 


2284 


2285 


2351 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The messenger service 
has not been started. 


The name is not on the 
local computer. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


Remarks 


DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


Data returned at a level of 0 provides only the name of the user. A level 1 structure 
provides the name of the user and whether or not message forwarding is available, 
and if so, to whom the messages are forwarded. 


NetMessageNameGetInfo requires that the messenger service be started. 
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Related Information 
For information on listing all user name entries in a message name table, see 
“NetMessageNameEnum” on page 3-179. 
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NetMessageNameUnFwd | 
The NetMessageNameUnFwd (admin) function stops forwarding a user’s messages 
to another user. 


Syntax 


#include <netcons.h> 
#include <message. h> 


unsigned far pascal 
NetMessageNameUnFwd(servername, name) 
const char far * servername; 

const char far * name; 


where: 


® servername points to an ASCIIZ string containing the name of a remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ name points to an ASCIIZ string specifying the user name whose message 
forwarding is to be canceled. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_REM_NOT_LIST 51 This remote computer 
is not listening. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_NoNetworkResource 2105 A network resource 
shortage occurred. 

NERR_BufTooSmall 2123 The buffer is too small . 
for fixed-length data. 

NERR_RemoteErr 2127 A remote API error 


has occurred. 
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Manifest 
NERR_OSZ2IoctlError 


NERR_NetworkError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_NameNotFound 


NERR AlreadyExists 


NERR_TooManyNames 


NERR _ NamelInUse 


NERR_MsgNotStarted 


NERR_NotLocalName 


NERR_ RemoteFull 


NERR_NameNotForwarded 


NERR_DuplicateName 


NERR_DeleteLater 


NERR InvalidComputer 


Value 
2134 


2136 


2138 


2139 


2140 


2141 


2213 


2276 


22I1 


2283 


2284 


2285 


2287 


2288 


2297 


2298 


2351 


Meaning 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The message alias 
cannot be found on the 
local area network. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


The message alias is 
currently in use—try 
again later. 


The messenger service 
has not been started. 


The name is not on the 
local computer. 


The message alias table 
on the remote station 
is full. 


Messages for this alias 
are not currently 
forwarded. 


A duplicate message 
alias exists on the local 
area network. 


This message alias will 
be deleted later. 


The specified computer 
name is invalid. 
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Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


NetMessageNameUnFwd requires that the messenger service be started. 


Related Information 


For information on: 


Forwarding a user’s messages to another user—See “NetMessageNameFwd” on 
page 3-182. 


Listing the user name entries in a message name table—See 
“NetMessageNameEnum” on page 3-179. 


The messenger service—See “Service Category” on page 3-298. 
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Named Pipe Category 


Description 


The functions in the Named Pipe category control interprocess communication (IPC) 
for named pipes. 


For information on the following functions, see the JBM Operating System/2 

Technical Reference Version 1.2 Programming Reference. 
DosBufReset (/ocal, DOS) 
DosCaliNmPipe (/ocal, DOS) 
DosClose (Jocal, DOS) 
DosConnectNmPipe (/ocal) 
DosDisConnectNmPipe (/oca/) 
DosDupHandle (Jocal, DOS) 
DosMakeNmPipe (local) 
DosOpen (local, DOS) 
DosPeekNmPipe (/ocal, DOS) 
DosQFHandState (/ocal, DOS) 
DosQHandType (/ocal, DOS) 
DosQNmPHandState (local, DOS) 
DosQNmPipelnfo (Jocal, DOS) 
DosQNmPipeSemState (/ocal) 
DosRead (Jocal, DOS) 
DosReadAsync (Jocal) 
DosSetFHandState (local, DOS) 
DosSetNmPHandState (Jocal, DOS) 
DosSetNmPipeSem (/ocal) 
DosTransactNmPipe (/ocal, DOS) 
DosWaitNmPipe (local, DOS) 
DosWrite (Jocal, DOS) 
DosWriteAsync (local). 


The functions in the Named Pipe category control interprocess communication (IPC) 
for named pipes. They are used with the OS2.H and NETCONS.H include files. 


These functions are provided by the base operating system and supported by the 
OS/2 LAN Server accross the network. 


A named pipe is a bidirectional interprocess communication facility that allows two 
processes, either local or remote, to communicate with each other over the network. 
A process that creates a named pipe is known as a server process, and a process that 
establishes a connection to a named pipe is known as a client process. 
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To create an instance of a named pipe on the local computer, an application must 
call the DosMakeNmPipe function. This function specifies information that enables 
the server process to control the named pipe and allows client processes to access the 
named pipe. In order to create a named pipe, DosMakeNmPipe requires the 
following: 


¢ The name chosen for the named pipe—the format is \pipe\name for a local 
named pipe. 


¢ The directions (inbound, outbound, and full-duplex) that the named pipe can 
send and receive data. 


e An indication as to whether the handle of the named pipe can be passed to 
spawned processes. 


¢ The number of concurrent instances of the named pipe that can be created. 


¢ The low-level parameters used by the OS/2 program. 


An inbound or outbound named pipe (synonymous with anonymous pipes used with 
other multi-tasking operating systems) allows a process only to read or write by way 
of one handle. A full-duplex named pipe allows a process to both read and write 
data by way of one handle. 


In some applications (especially those that were developed before the OS/2 Version 
1.1 program or those that emulate anonymous pipes), the handle of a named pipe 
cannot be passed to a spawned process. 


Each time DosMakeNmPipe is called with the same parameter information, another 
instance of the named pipe is created. Each instance is associated with a unique 
handle which is returned by DosMakeNmPipe. Thus, if DosMakeNmPipe is called 
five times with the same information, five different instances (or handles) of the same 
named pipe are created. 


Other low-level operating system parameters such as the stream type and blocking 
mode of the named pipe can be set. Even though a server process creates a named 
pipe on a computer, client processes cannot access an instance of that named pipe 
until the server process calls DosConnectNmPipe. This function informs the system 
that a client process has permission to access an instance of the named pipe and also 
returns a handle to the named pipe. 


To become a client process, an application must open an instance of the named pipe 
by calling the DosOpen function. DosOpen returns a handle to the client process 
that can be passed to other named pipe reading and writing functions. If DosOpen 
returns the ERROR_PIPE_BUSY error code (pipe currently being accessed by 
another process), the client process should call DosWaitNmPipe to wait for the 
named pipe to become available. DosWaitNmPipe can be configured to time out 
after a particular period of time, or to wait indefinitely for an instance of the named 
pipe. 


When an instance of the named pipe becomes available, the DosWaitNmPipe 
function is allowed to return to the waiting client process. At this point, the client 
process can call DosOpen to open the named pipe. After a client process has opened 
an instance of a named pipe, the client process can begin to read and write to the 
named pipe. To perform these tasks, the client process should call the DosRead and 
DosWrite functions. Both of these functions accept the handle returned by 
DosOpen, and operate on the same thread of execution as the client process. If a 
server or client process requires that the reading and writing of named pipes be 
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executed on a separate thread, the process can call the DosReadAsync and 
DosWriteAsync functions. Note that a remote named pipe can be written to by 
specifying the pipe name as follows: 


\\server\pipe\name 





A process can also cali the DosBufReset function to force all data to be written to a 
named pipe; normally, data written to a named pipe is held temporarily in a data 
buffer. 


Note that output cannot be redirected to a named pipe. 


Since a named pipe must be written to before it is read from, a process can call 
DosPeekNmPipe to see if there is any data written to a named pipe. 
DosPeekNmPipe reads the data in a named pipe but does not remove the data. 


If necessary, either a server or client process can call DosDupHandle to replicate a 
handle to a named pipe. DosDupHandle returns a new handle to the same instance 
of a named pipe that an old handle represented. This handle can be passed to any 
named pipe function that could use the old handle. 


Two functions are provided that decrease the overhead involved in writing to and 
reading from a named pipe. These two functions are DosTransactNmPipe and 
DosCaliNmPipe. DosTransactNmPipe writes a message to and then reads a message 
from an opened named pipe. DosCaliNmPipe opens, writes to, reads from, and then 
closes a named pipe. This four-in-one process is helpful when implementing a 
remote procedure call (RPC) on the network. 


When a client process no longer requires access to a named pipe, the DosClose 
function can be called to close the named pipe. 


When a server process no longer requires an instance of a named pipe, the server 
process calls DosDisconnectNmPipe to remove that instance of the named pipe by 
specifying its handle. If a client process is still accessing the named pipe, 
DosDisconnectNmPipe forces the client process off. 


Five functions are provided that enable server or client processes to obtain 
information about a named pipe or its handle, as follows: 


Function Purpose 

DosQFHandState Determines whether the handle can be inherited 
and if write-behind is allowed. 

DosQHandType Returns the type of handle. 

DosQNmPHandState Returns the low-level parameters associated with 


a handle and the operating mode of the pipe; 
declares the instance count. 


DosQNmPipelnfo Returns the size of buffers and the number of 
instances currently available. 


DosQNmPipeSemState Returns the state of a semaphore associated with 
a named pipe. 
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The OS/2 LAN Requester/Server software provides three functions that enable server 
or client processes to set specific information about a named pipe that can be 
queried. The functions and settable parameters are as follows: 


Function Purpose 

DosSetFHandState Sets whether a handle of a named pipe can be 
inherited and if write-behind is allowed. 

DosSetNmPHandState Sets low-level parameters associated with pipes 
such as reading and writing mode. 

DosSetNmPipeSem Sets the association of a semaphore to a named 
pipe. 


The transfer mode of a named pipe is set by either DosMakeNmPipe or 
DosSetNmPHandState; a named pipe transfers data in byte-stream or 
message-stream mode. 


A named pipe operating in byte-stream mode operates like an anonymous pipe 
where all data written is transferred without any special processing performed on it. 
When operating in message-stream mode, a named pipe can distinguish between the 
different messages (and size of each message) read from and written to that named 
pipe. 


Named pipes are designed so that a client process has no requirement for the type of 
resource it is opening (pipe or file). Client processes use the DosOpen, DosRead, 
and DosClose functions to open, read, and close both types of resources without 
reference to one resource being a file and the other a named pipe. 


The following table describes the transition state of a named pipe, based on the 
action a server or client process indicates: 


Current State Action/Process Next State 

Pipe does not exist DosMakeNmPipe, NP_DISCONNECTED 
server 

NP_DISCONNECTED DosConnectNmPipe, NP_LISTENING 
server 

NP_LISTENING DosOpen, client NP_CONNECTED 

NP_CONNECTED DosDisconnectNmPipe, DISCONNECTED 
server 

NP_CONNECTED DosClose, client NP_CLOSING 

NP_CLOSING DosDisconnectNmPipe, DISCONNECTED 
server 

NP_CONNECTED DosClose, server NP_CLOSING 


Note: The OS/2 DosChgFilePtr function (and other functions that perform seek 
operations on files) does not work with named pipes. 
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DOS Considerations 
Under DOS, the functions can be executed only on a remote server that has 
interprocess communication (IPC) shares. 


DOS supports only client processes; a pipe must have already been created and 
connected on a remote server. Child processes inherit the open file handles of a 
parent process. DOS does not support asynchronous reading and writing of named 
pipes. 

Note: The Family API (FAPI) replacement library routine for DosOpen provides 
support for DASD opens (open Mode Flag 0x8000). Since DOS does not 
support this operation, pipe operations on this type of file handle will return 
ERROR_INVALID_HANDLE rather than ERROR _ BAD _ PIPE. 


DosBufReset works differently depending on which version of DOS you are 
programming under. Under version 3.3 and 4.0, DosBufReset returns 0 after 
resetting a closed named pipe. If the handle is to a named pipe that has already been 
closed, DosBufReset returns ERROR_BROKEN PIPE. 


Under DOS 3.3 and 4.0, DosBufReset waits for the pipe to be emptied. 
Related Information 
For information on: 


e Anonymous pipes, named pipes, or [PC—See the IBM Operating System/2 
Technical Reference Version 1.2 Programming Reference, Volume 1. 


¢ For a detailed description of each function—See the JBM Operating System/2 
Technical Reference Version 1.2 Programming Reference. 


Chapter 3. API Function Descriptions 3-195 


Remote Utility Category 


Description 


NetRemoteCopy (/ocal, DOS)—See “NetRemoteCopy” on page 3-197. 
NetRemoteExec (local, server)—See “NetRemoteExec” on page 3-200. 
NetRemoteMove (/ocal, DOS)—See “NetRemoteMove” on page 3-203. 
NetRemoteTOD (DOS)—See “NetRemoteTOD” on page 3-206. 


The functions in the Remote Utility category enable applications to copy and move 
remote files, remotely execute a program, and access the time-of-day information on 
a remote server. They are used with the REMUTIL.H and NETCONS.H include 
files. 


The NetRemoteCopy function performs optimized file copying. Files on a remote 
server are copied without physically moving the files to and from the local requester. 
The source and destination must be on the same server. 


The NetRemoteMove function moves files or directories from one location to 
another on a remote server without physically moving the data if the source and 
destination are on the same drive. If source and destination are on different drives, 
the move does not require shuffling the data to and from the local requester. 


To execute a program on a remote server, an application calls the NetRemoteExec 
function. NetRemoteExec performs the same tasks as the OS/2 DosExecPgm 


function, but on another network server. 


The NetRemoteTOD function returns time-of-day information from a remote server. 


DOS Considerations 


Data Structures 


Under DOS, the functions in the Remote Utility category enable applications to 
copy and move remote files and access the time-of-day information on a remote 


server. Attempting to execute the functions on a local requester returns 
NERR_RemoteOnly. 


The function NetRemoteCopy uses data structure copy_info. The function 
NetRemoteMove uses data structure move_info. The function NetRemoteTOD uses 
data structure time_of_day_info. These data structures are described following the 
syntax descriptions in each function section. 


NetRemoteExec does not use a data structure. 
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NetRemoteCopy 


Syntax 


The NetRemoteCopy (local, DOS) function copies one or more files from one 
location to another on a remote server. 


#include <netcons.h> 
#include <remutil.h> 


unsigned far pascal 
NetRemoteCopy (sourcepath, destpath, sourcepass, destpass, 


const char far 
const char far 
const char far 
const char far 
unsigned short 
unsigned short 
char far * 

unsigned short 


where: 


openflags, copyflags, buf, buflen) 
* sourcepath; 
* destpath; 
* sourcepass; 
* destpass; 
openflags; 
copyflags; 
buf; 
buflen; 


¢ sourcepath points to an ASCIIZ string containing the path name of the files to 
be copied (wildcards can be used). sourcepath must begin with either a 
redirected drive or a UNC name. 


e destpath points to an ASCIIZ string containing the path name to which 
sourcepath is to be copied. For a wildcard sourcepath, destpath must be a 
directory. destpath must begin with either a redirected drive or a UNC name. 


© sourcepass is reserved and must be NULL. 


e destpass is reserved and must be NULL. 


¢ openflags specifies how destpath will be opened. openflags is defined as follows: 


Bit 
0-1 


Meaning 


Used if destpath exists. If 0, the open fails. If 1, the file is 
appended. If 2, the file is overwritten. 


Reserved, with a value of 0. 


Used if destpath does not exist. If 0, the open fails. If 1, the file is 
created. 


Reserved, with a value of 0. 


¢ copyflags specifies how the file copy is done. copyflags is defined as follows: 


Bit 


Meaning 
If 1, destpath must be a file. If bit 0 is set, bit 1 must be 0. 
If 1, destpath must be a directory. If bit 1 is set, bit 0 must be 0. 


If 0, destpath is opened in binary mode. If 1, destpath is opened in 
text mode. 


If 0, sourcepath is opened in binary mode. If 1, sourcepath is 
opened in text mode. 
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Bit Meaning 


4 If 1, all writes are verified. 


5-15 Reserved. 


e buf points to the copy_info data structure. 


e buflen specifies the size (in bytes) of the buf memory area. 


Return Status of File Copy 
NetRemoteCopy returns data in the following form: 


Return Codes 


struct copy_info { 
unsigned ci_num_copied; 
char ci_err_buf[1]; 


rs 


where: 


¢ ci_num_copied indicates the number of files that were copied. 


¢ ci_err_buf is a variable-length ASCIIZ string containing error information 


pertaining to the file copy. 


Manifest 
NERR_SUCCESS 


ERROR_FILE_NOT_FOUND 
ERROR_PATH NOT FOUND 


ERROR_ACCESS_DENIED 


ERROR_NO_ MORE FILES 


ERROR_SHARING_VIOLATION 


ERROR_FILE_EXISTS 
ERROR_INVALID_ PARAMETER 


NERR_NetNotStarted 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


3-198 LAN Server Application Programmer’s Reference 


Value 


18 


32 


80 
87 


2102 


2123 


2134 


2138 


Meaning 


No errors were 
encountered. 
The file was not found. 


The path was not 
found. 


Administrative 
privilege is required. 
No more files are 
available. 


A sharing violation 
occurred. 


The file already exists. 


The specified 
parameter is invalid. 


The redirector 
NETWKSTA.EXE has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


Manifest Value Meaning 


NERR_BadSource 2381 The source path is 
illegal. 

NERR_BadDest 2382 The destination path is 
illegal. 

NERR_DifferentServers 2383 The source and 


destination paths are 
on different servers. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFSCtl 
¢ DosDevIOCtlh(NIOCNETCOPY1_1). 


Remarks 
Currently, the source and destination for the file copy must be on the same server or 
an error results. The following cases are valid: 


e The source and destination are both files. The source file is copied to the 
destination file, subject to openflags and copyflags limitations. 


e The source is a file or wildcard and the destination is a directory. The source 
files are copied to the destination directory, subject to openflags and copyflags 
limitations. 


Related Information 
For information on: 


e Listing the shared resources of a server—See “NetShareEnum” on page 3-350. 
¢ Moving remote files between servers—See “NetRemoteMove” on page 3-203. 


e Share passwords—See “Share Category” on page 3-337. 
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NetRemoteExec 


Syntax 


The NetRemoteExec (local, server) function executes a program located on a remote 
server. 


#include <netcons.h> 
#include <remutil.h> 


unsigned far pascal 
NetRemoteExec (reserved1, objnamebuf, objnamebufl, asyntraceflags, 


argpointer, envpointer, returncodes, pgmpointer, 
reserved2, remexecflags) 


char far * reserved]; 
char far * objnamebuf ; 
unsigned objnamebuf1; 
unsigned asyntraceflags; 


const char far * argpointer; 
const char far * envpointer; 


char far * returncodes; 
const char far * pgmpointer; 
char far * reserved2; 


unsigned short remexecflags; 


where: 


e 


reservedl is a reserved pointer with the value of -1. 


objnamebuf points to the name of the object, such as a dynamic-link library. 
The NetRemoteExec function copies a name to this buffer if it could not 
successfully load and start the specified program. 


objnamebufl specifies the size (in bytes) of the objnamebuf memory area. 


asyntraceflags specifies the asynchronous and trace flags. asyntraceflags is 
defined as follows: 


Value Meaning 

0 Synchronous process. 

I Asynchronous process without result code. 
2 Asynchronous process with result code. 


argpointer points to a set of ASCIIZ strings containing the arguments of the file 
to be executed. 


envpointer points to a non-NULL ASCIIZ string specifying the environment for 
the file to be executed. 


returncodes points to an OS/2 data structure containing the return codes 
resulting from the file execution. This is the same data structure used with the 
OS/2 DosExecPgm function. For more information on the return codes and the 
DosExecPgm function, see the JBM Operating System/2 Technical Reference 
Version 1.2 Programming Reference, Volume 2. 


pgmpointer points to an ASCIIZ string containing only the name and extension 
of the file to be executed. 


reserved2 is a reserved pointer with the value 0. 
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Return Codes 


e remexecflags specifies the remote executable flags that control program 


execution. remexecflags is defined as follows: 


Manifest 


If 0, a message mode pipe is 
used for standard input. If 1l,a 
character mode pipe is used for 
standard input. 


If 0, the OS/2 DosCWait 
function waits for the child 
process to finish before 
returning. If 1, DosC Wait waits 
for all spawned processes to 
finish before returning. 


If 0, map SIGINTR and 
SIGBREAK to SIGKILL when 
remoting standard signals. If 1, 
the send signals as received. For 


Bit Meaning 
0 REM _ PIPE MODE 
1 REM_ WAIT MODE 
2 REM _SIGL_ MODE 
3-15 

Manifest 


NERR_SUCCESS 


ERROR INVALID PARAMETER 


NERR _InternalError 


NERR_RunSrvPaused 


NERR_ ErrCommRunSrv 


NERR_ErrConnRunSrv 


NERR_ErrorExecingGhost 


NERR_ShareNotFound 


more information on OS/2 
signals, see the IBM Operating 
System/2 Technical Reference 
Version 1.2 Programming 
Reference, Volume 1. 


Reserved, with a value of 0. 


Value 


87 


2140 


2385 


2389 


2390 


2391 


2392 


Meaning 


No errors were 
encountered. 


The specified 
parameter is invalid. 


An internal error has 
occurred. 


The run server you 
requested using the 
NET RUN command 
is paused. 


An error occurred 
when communicating 
with a run server. 


An error occurred 
when connecting to 
run server. 


An error occurred 
when starting a 
background process. 


The shared resource 
you are connected to 
could not be found. 


Chapter 3. API Function Descriptions 3-201 


Manifest Value Meaning 


NERR_PgmNotFound 2394 The program was not 
found. 


Remarks 
The NetRemoteExec function is a network extension of the OS/2 DosExecPgm 
function. 


The executed process is run on the computer connected to the current drive of the 
caller. If the current drive of the caller is on a remote server, the child process is 
executed on that server. If the current drive of the caller is a local drive, the child 
process is executed locally. 


The NetRemoteExec function requires that a remotely executed process inherit one 
of the following handles: 


Handle Meaning 

0 Standard input (stdin) 

1 Standard output (stdout) 
Z Standard error (stderr) 


When the NetRemoteExec function initiates an asynchronous process, the process 
identification (PID) returned to the first word of the ReturnCodes data structure is a 
valid local PID that represents the remote program. The PID can be passed to the 
OS/2 DosFlagProcess function to: 


e Send signals to the remote process 
¢ Call the OS/2 DosCWait function to wait for the remote process to exit 
¢ Call the OS/2 DosKillProcess function to end the process. 
Related Information 
For information on: 
e Listing resources of a server—See “NetShareEnum” on page 3-350. 
e Listing the servers of a network—See “NetServerEnum2” on page 3-289. 


e Executing a command on a server—See “NetServerAdminCommand” on 
page 3-284. 


e Executing a program—See OS/2 DosExecPgm (JBM Operating System/2 
Technical Reference Version 1.2 Programming Reference, Volume 1). 


¢ OS/2 DosCWait—See OS/2 DosCWait (JBM Operating System/2 Technical 
Reference Version 1.2 Programming Reference, Volume 1). 
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NetRemoteMove 


Syntax 


The NetRemoteMove (local, DOS) function moves one or more files from one 
location to another on a server. 


#include <netcons.h> 
#include <remutil.h> 


unsigned far pascal 
NetRemoteMove(sourcepath, destpath, sourcepass, destpass, 


openflags, moveflags, buf, buflen) 


const char far * sourcepath; 
const char far * destpath; 
const char far * sourcepass; 
const char far * destpass; 


unsigned openflags; 
unsigned moveflags; 
char far * buf; 


unsigned short  buflen; 


where: 


sourcepath points to an ASCIIZ string containing the path name of the file to be 
moved (wildcards can be used). sourcepath must begin either with a redirected 
drive or a universal naming convention (UNC) name. 


destpath points to an ASCIIZ string containing the path name to which 
sourcepath is to be moved. For a wildcard sourcepath, destpath must be a 
directory. destpath must begin either with a redirected drive or a UNC name. 


sourcepass is reserved and must be NULL. 
destpass is reserved and must be NULL. 


openflags specifies how destpath will be opened. openflags is defined as follows: 


Bit Meaning 

0-1 Used if destpath exists. If 0, the open fails. If 1, the file is 
appended. If 2, the file is overwritten. 

2-3 Reserved, with a value of 0. 

4 Used if destpath does not exist. If 0, the open fails. If 1, the file is 
created. 

5-15 Reserved, with a value of 0. 


moveflags establishes control for the file move. moveflags is defined as follows: 


Bit Meaning 

0 If 1, destpath must be a file, and bit 1 must be 0. 

1 If 1, destpath must be a directory, and bit 0 must be 0. 
2-15 Reserved; the value of these bits must be 0. 


buf points to the move_info data structure. 
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¢ buflen specifies the size (in bytes) of the buf memory area. 


Return Status of File Move 
The NetRemoteMove function returns data in the following form: 


struct move_info { 
unsigned mi_num_moved; 
char mi_err_buf[1]; 
}; 
where: 
* mi_num_moved indicates the number of files that were moved. 
¢ mi_err_buf is a variable-length ASCIIZ string containing error information 
pertaining to the move operation. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were encountered. 
ERROR_FILE_NOT_FOUND 4 The file was not found. 
ERROR_PATH_NOT_FOUND 3 The path was not found. 
ERROR_ACCESS_ DENIED 5 Administrative privilege is 
required. 
ERROR_NO_MORE_FILES 18 No more files are available. 
ERROR_SHARING_VIOLATION 32 A sharing violation occurred. 
ERROR_FILE_EXISTS 80 The file already exists. 
ERROR_INVALID_PARAMETER 87 The specified parameter is 
invalid. 
NERR_BufTooSmall 2123 The buffer is too small for 
fixed-length data. 
NERR_BadSource 2381 The source path is illegal. 
NERR_BadDest 2382 The destination path is illegal. 
NERR_DifferentServers 2383 The source and destination 


paths are on different servers. 


Remarks 
If the source and destination files are in the same directory, NetRemoteMove 
renames the source file. When the source and destination are on different drives, 
NetRemoteMove moves sourcepath to destpath and then deletes sourcepath. 


Currently, the source and destination path names (sourcepath and destpath) supplied 
to the NetRemoteMove function must be on the same server. The following cases 
are valid: 


¢ The source and destination are both files. The source file is copied to the 
destination file, subject to openflags and moveflags limitations. 


e The source is a file or wildcard and the destination is a directory. The source 
files are copied to the destination directory, subject to openflags and moveflags. 
limitations. 
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Related Information 
For information on: 


¢ Copying a file from one network location to another—See “NetRemoteCopy” on 
page 3-197. 


¢ Determining if a driver letter is local or redirected to a remote server—See 
“NetUseGetInfo” on page 3-380. 


e Listing available resources on a server—See “NetShareEnum” on page 3-350. 
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NetRemoteTOD 


Syntax 


The NetRemoteTOD (DOS) function returns the time of day on a server. 


#include <netcons.h> 
#include <remutil.h> 


unsigned far pascal 
NetRemoteTOD(servername, buf, buflen) 
const char far * servername; 

char far * buf; 

unsigned short  buflen; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ buf points to the time_of_day_info data structure. 


¢ buflen specifies the size of the buf memory area. 
Return Time-of-Day Information on a Server 


The NetRemoteTOD function returns data in the following form: 


struct time_of_day_info { 


unsigned long  tod_elapsedt; 
unsigned long _tod_msecs; 
unsigned char __tod_hours; 
unsigned char  tod_mins; 
unsigned char _tod_secs; 
unsigned char _tod_hunds; 
unsigned short tod_timezone; 
unsigned short tod_tinterval; 
unsigned char  tod_day; 
unsigned char tod_month; 
unsigned short tod_year; 
unsigned char tod_weekday; 
}; 

where: 


¢ tod_elapsedt indicates the number of seconds that have elapsed since January 1, 
1970. 


¢ tod_msecs indicates the current millisecond. 

¢ tod_hours indicates the current hour. 

¢ tod_mins indicates the current minute. 

¢ tod_secs indicates the current second. 

¢ tod_hunds indicates the current hundredths of a second. 


¢ tod_timezone indicates the timezone of the server; calculated (in minutes) from 
the greenwich mean time (GMT) zone. 


¢ tod_tinterval indicates the time interval for each tick of the clock. Each integral 
integer represents 0.0001 second. 
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¢ tod_day (i through 31) indicates the day of the month. 
¢ tod_month (1 through 12) indicates the month. 
¢ tod_year indicates the year, starting with 1980. 


¢ tod_weekday indicates the day of the week (0 means Sunday, 6 means Saturday). 


Return Codes 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 

NERR_BufTooSmall 2123 The buffer is too small for 
fixed-length data. 

NERR_WkstaNotStarted 2138 The Requester service has not been 
started. 

NERR _InvalidComputer 2351 The specified computer name is 
invalid. 


Related Information 
For information on listing the servers of a network, see “NetServerEnum2” on 
page 3-289. 
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Requester Category 
NetWkstaGetInfo (partially admin, DOS)—See “NetWkstaGetInfo” on page 3-225. 


NetWkstaSetInfo (admin, DOS)—See “NetWkstaSetInfo” on page 3-227. 
NetWkstaSetUID2 (DOS)—See “NetWkstaSetUID2” on page 3-231. 


The functions in the Requester category control the operation of requesters. They 
are used with the ACCESS.H, NETCONS.H, and WKSTA.H include files. 


Description 
The requester functions enable applications to: 


¢ Log a user name onto a requester 
e Log a user name off of a requester 
e Execute a Jogon script on a logon server for a user name 


¢ Control configuration of a requester. 


To log a user name onto or off a requester or to execute a logon script for a user 
name, an application calls the NetWkstaSetUID2 function. 


To configure a requester, an application calls the NetWkstaSetInfo function. The 
NetWkstaGetInfo function returns information about the configuration of a 
requester. 


Note: The domain name of the requester (the wki0_langroup component in the 
wksta_info data structure) must not duplicate any computer name or user 
name on the network. 


Giving a domain the name of a computer causes startup problems for one of 
two namesakes. If the like-named computer is started before the domain, no 
other computer in the domain will be able to start. And, conversely, if any 
computer in the like-named domain is started, the computer going by the 
domain name will be unable to start. 


For more information on domains, see the IBM Operating System/2 Local 
Area Network Server Version 1.2 Network Administrator's Guide. 


DOS Considerations 
Under DOS, the functions in the Requester category control the operation of 
requesters. They can be executed only on a local requester. Attempting to execute 
the functions on a remote server returns ERROR_NOT_SUPPORTED. 


Certain parameters are not used under DOS and therefore cannot be set. However, 
validity checks are done on most of the unused parameters for future expansion. 
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Data Structures 


The following table describes the parameters that are used and whether validity 
checks are perfomed on them: 


Parameter 


charwait 
chartime 
charcount 


errlogsz 


printbuftime 


wrkheuristics 


Used Validity Checked 
No Yes 
Yes Yes 
Yes Yes 
No Yes 
No Yes 
No No 


The NetWkstaGetInfo (level 0, 1, and 10) and NetWkstaSetInfo (level 0 and 1) 
functions accept or return data at the specified level of detail, using the wksta_info 
data structure. 


Requester Information (Level 0) 


struct wksta_info_0 { 


unsigned 
unsigned 
char far 
char far 
char far 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char far 
char far 
unsigned 


short 
Tong 


* 
* 
* 
* 


char 

char 

Tong 

short 
long 

short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 


short 


wki0_reserved_1; 
wki0_reserved_2; 
wki0_root; 
wki0_computername; 
wki0_username; 
wki0_langroup; 
wki0_ver_major; 
wki0_ver_minor; 
wki0_reserved_3; 
wki0_charwait; 
wki0_chartime; 
wki0_charcount; 
wki0_reserved_4; 
wki@_reserved_5; 
wki9_keepconn; 
wki0_keepsearch; 
wki0_maxthreads ; 
wki0_maxcmds; 
wki0_reserved_6; 
wki0_numworkbuf ; 
wki0_sizworkbuf; 
wki0_maxwrkcache; 
wki0_sesstimeout; 
wki0_sizerror; 
wki0_numalerts; 
wki@_numservices; 
wki0_errlogsz; 
wki0_printbuftime; 
wkiQ_numcharbuf; 
wki0_sizcharbuf; 
wki0_logon_server; 
wki0_wrkheuristics; 
wki@_mailslots; 
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where: 


wki0_reserved_1, wki0_reserved_2, wki0_reserved_3, wki0_reserved_4, 
wki0_reserved_5, and wkiO_reserved_6 are reserved, and must be 0. 


wkiO_root points to an ASCIIZ string containing the path to the IBMLAN 
directory of the computer (the recommended default path is \IBMLAN). 


wki0_computername points to an ASCIIZ string containing the computer name 
of the local requester being configured. 


wki0_username points to an ASCIIZ string containing the user’s name logged on 
the requester. 


wki0_langroup points to an ASCIIZ string containing the name of the domain to 
which the requester belongs. 


wkiO_ver_major specifies the major version number of the OS/2 LAN 
Requester/Server software running on the computer. 


wki0_ver_minor specifies the minor version number of the OS/2 LAN 
Requester/Server software running on the computer. 


wki0_charwait indicates the number of seconds the requester will wait for a 
remote serial or communication device to become available. 


wki0_chartime indicates the number of milliseconds the requester will wait to 
collect data to send to a remote serial or communication device. 


wkiO_charcount indicates the number of bytes of information the requester will 
send to a remote serial or communication device. 


wki0_keepconn indicates the number of seconds that an inactive connection from 
the requester to a resource of a server will be maintained. 


wkiO_keepsearch indicates the number of seconds that an inactive search will 
continue. 


wki0_maxthreads indicates the number of threads the requester can dedicate to 
the network. 


wki0_maxcmds indicates the number of simultaneous network device driver 
commands that can be sent to the network. 


wki0_numworkbuf indicates the number of internal buffers the requester has. 
wkiO_sizworkbuf indicates the size (in bytes) of each internal buffer. 


Use the following formula to determine the maximum values for both 
numworkbuf and the sizworkbuf parameters: 


(sizworkbuf + 268) * numworkbuf < 65,515 
Default value: 4096 
Minimum value: 1024 


Maximum value: 16384 


wki0_maxwrkcache indicates the maximum size (in bytes) of an internal cache 
buffer. 


wkiO_sesstimeout indicates the number of seconds that are waited before 
disconnecting an inactive session between a requester and a server. 


wki0_sizerror indicates the size (in bytes) of an internal error buffer. 
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wki0_numalerts indicates the maximum number of clients that can receive alert 
messages. 


Note that each mailslot or semaphore registered by the NetAlertStart function is 
a different client, and that the alerter service registers at least three clients when 
it begins to run. For more information on alerts, see “Alert Category” on 

page 3-29. 


wkiO_numservices indicates the number of services that can be started on the 
requester at any time. For more information on services, see “Service Category” 
on page 3-298. 


wki0_errlogsz indicates the maximum size (in kilobytes) of the error log file of 
the requester. 


wkiO_printbuftime indicates the number of seconds waited before closing inactive 
compatibility-mode print jobs. 


wkiO_numcharbuf indicates the number of character pipe buffers and device 
buffers the requester can have. 


wkiO_sizcharbuf indicates the maximum size (in bytes) of a character pipe buffer 
and device buffer. 


wki0_logon_server points to an ASCIIZ string indicating the name of the domain 
controller of the requester. A NULL string indicates no logon servers are 
available. If the string is \\*, any available logon server is queried. 


wkiO_wrkheuristics points to an ASCIIZ string of flags used to control a 
requester’s operation. The heuristics default to values that are optimal for most 
configurations and normally need not be changed. 


The default value for wki0_wrkheuristics is defined as follows: 
wrkheuristics = 11111111213111111100010110201110 

The maximum value for wki0_wrkheuristics is defined in IBMLAN.INI as 
follows: 

wrkheuristics = 11221211223111111111519111213170 

If a partial string is specified, the default values are used for the remaining 


heuristics. If the string is NULL or is not present in the IBMLAN.INI file, the 
default string is used. 


If the values used are other than those listed (0 or 1 where no value is listed), 
errors may occur. 


The characters (from left to right) are defined as follows. Unless otherwise 
defined, 0 turns off a heuristic feature, and 1 turns on the feature. 


The parameters and their descriptions are as follows: 
Parameter Description 


sizworkbuf Sets the size of requester buffers, in bytes. Increase 
sizworkbuf to transfer large groups of data, such as 
database records, on the network. This value should be 
a multiple of 512. It should be the same for every 
requester on the network and equal to the sizreqbuf 
value used by servers. 


When the numworkbuf and sizworkbuf parameters are 
used in the following formula, they should not be 
greater than 64KB: 
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(sizworkbuf + 268) * numworkbuf < 65515 
Default value: 4096 


Minimum value: 1024 


Maximum value: 16384 


wrkheuristics 


Sets a variety of requester fine-tuning options. Each 


digit has an independent meaning. Missing digits are 
assumed to be the defaults as described. Except where 
noted, each is a binary digit where 0 means off or 
inactive, while 1 means on or active. The following are 
the meanings of the digits: 


Digit Meaning 


0 
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Request opportunistic locking of files. The 
default is 1. 


When this heuristic is active, it allows a file 
opened in deny none sharing mode to be locked 
by the server (provided there are no other access 
requests), so that buffering can be used to 
enhance performance. The Server service 
assumes that the first requester is the only active 
process using that file and will prevent a second 
requester from accessing the file until buffer data 
is flushed (written to disk). 


Do performance optimization for batch files. 
Heuristic 0 (opportunistic locking) must be set to 
1. The default is 1. 


When this heuristic is active (set to 1), a batch 
file on the server executing on the requester is 
kept in the requester’s buffer to prevent a request 
across the LAN for each line of the batch file. 
The batch file is opened and closed with each 
line executed; when this heuristic is inactive (set 
to 0), the close causes buffer data to be flushed. 


Do asynchronous unlock and write unlock as 
follows: 


Value Meaning 


0 Never 

1 Always 

2 Only on an OS/2 LAN Server virtual 
circuit. 


The default is 1. 


With this heuristic, files in the requester buffer 
are unlocked in the buffer, and processing 
continues without waiting for confirmation from 
the server. Any errors occurring at the server are 
reported later. Generally, the only errors that 
might occur are hard media errors, such as disk 
full or a loss of power to the server. (A virtual 


circuit in this discussion is a NETBIOS™ session 
connection to another machine through a LAN.) 


3 Do asynchronous close and write close as 
follows: 


Value Meaning 


0 Never 

1 Always 

2 Only on an OS/2 LAN Server virtual 
circuit. 


The default is 1. 


This heuristic performs the same function in the 
close operation as wrkheuristic 2 performs in the 
unlock operation. 


4 Buffer named pipes and serial devices. The 
default is 1. 


This heuristic directs named pipes and 
communication devices through the requester’s 
buffers. 


5 Do combined lock read and write unlock as 
follows: 


Value Meaning 


0 Never 

1 Always 

2 Only on an OS/2 LAN Server virtual 
circuit. 


The default is 1. 
6 Use open and read. The default is 1. 


When this heuristic is active, a request to open a 
file also performs a read of size sizworkbuf from 
the beginning of the file to the requester’s work 
buffer. This action anticipates that the data is 
subsequently read, saving an additional request 
across the LAN. 


7 Reserved. This must be set to 1. 
8 Use the chain send NETBIOS NCB as follows: 


Value Meaning 


0 Never 
1 Do if server’s buffer is larger 
2 Always (to avoid copy). 


The default is 1. 


When this heuristic is active, data packets larger 
than the LAN’s transmit buffer size are chained 
together, eliminating some packet transmissions 
across the LAN. 


NETBIOS is a trademark of International Business Machines Corporation. 
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10 


11 
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Buffer small read and write requests (reading and 
writing a full buffer) as follows: 


Value Meaning 


0 Never 

1 Always 

2 Only on an OS/2 LAN Server virtual 
circuit. 


The default is 1. 


When this heuristic is active and file access mode 
allows, requests to read or write data smaller 
than sizworkbuf are performed locally, in the 
requester’s buffer, avoiding additional trips 
across the LAN. The buffer is flushed when the 
file is closed or when the buffer is needed to 
satisfy other requests. 


This heuristic may enhance performance for 
applications that read, modify, and write back 
small records. 


Use buffer mode (assuming shared access is 


granted) as follows: 


Value Meaning 


0 Always read buffer size if request is 
smaller than buffer size. 

1 Use full buffer if file is open for reading 
and writing. 

2 Use full buffer if reading and writing 
sequentially. 

3 Buffer all requests smaller than the 


buffer size. 
The default is 3. 


Shared access means the file was opened in 
sharing mode. These options allow selective 
tuning of the buffer mode if any applications 
handle data in a manner conflicting with 
buffering. 


Use raw read and write server message block 
(SMB) protocols. The default is 1. 


Raw read and write SMB protocols transfer data 
across the LAN without SMB headers. These 
protocols are used to transfer large files directly 
between a big buffer in the server and a work 
cache in the requester. When a large file transfer 
initiates raw read and write SMB protocols, the 
NETBIOS session involved exclusively uses the 
LAN adapter cards on both the send and receive 
stations until the request completes. Polling 
ensures large buffers are available before the 
transfer begins. 


12 


13 


14 


15 


16 
17 


18 


This heuristic may significantly improve 
performance of large file transfers across the 
LAN. 


Use large raw read-ahead buffer. The default is 
1. 


This heuristic and heuristic 13 provide 
independent control over using raw SMB 
protocol for read-ahead and write-behind, 
respectively. Both are active with default values, 
but can be turned off to better suit a particular 
environment. 


Use large raw write-behind buffer. The default is 
1. 


See digits 11 and 12 for more information. 


Use read multiplexing server message block 
(SMB) protocols. The default is 1. 


This SMB protocol is used for large read 
requests if large buffers described in heuristic 11 
are unavailable, or raw SMB protocol is inactive. 
This protocol breaks transfers into buffer-size 
chunks (usually 4K B) and chains them together 
to satisfy the request. Exclusive use of LAN 
adapter cards does not occur. 


Use write multiplexing SMB protocols. The 
default is 1. 


This SMB protocol is used for large write 
requests if large buffers described in heuristic 11 
are unavailable, or raw SMB protocol is inactive. 
This protocol divides transfers into buffer-size 
chunks (usually 4K B) and chains them together 
to satisfy the request. Exclusive use of LAN 
adapter cards does not occur. 


Reserved. This must be set to |. 


Use same size small read-ahead or to sector 
boundary. The default is 1. 


When this heuristic is active, requests to read 
small data records cause read-ahead in multiples 
of the data record size, so a full buffer is read 
and sent to the requester. Because multiple 
records may not fit evenly in the buffer, the last 
record in the buffer may be incomplete. 
However, no data is lost. 


This heuristic is significant only if wrkheuristic 9 
is inactive. The server will detect small data 
records of the same size being read sequentially 
and will establish the read-ahead operation. 


Use same size small write-behind or to sector 
boundary. The default is 0. 


When this heuristic is active, requests to write 
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small data records cause write-behind in 
multiples of the data record size, so a full buffer 
is written to the server. Because multiple records 
may not fit evenly in the buffer, the last record 
written may be incomplete. However, no data is 
lost. 


This heuristic is significant only if wrkheuristic 9 
is inactive. The server will detect small data 
records of the same size being written 
sequentially and will establish the write-behind 
operation. 


Reserved. This must be set to 1. 


Flush pipes and devices on DosBufReset or 
DosClose as follows: 


Value Meaning 


0 Flush only files and devices opened by 
the caller. Spin until flushed (wait for 
confirmation before proceeding with 
other tasks). 


1 Flush only files and devices opened by 
the caller. Flush only once. 


2 Flush all files and all input and output 
of short-term pipes and devices. Spin 
until flushed. 


3 Flush all files and all input and output 
of short-term pipes and devices. Flush 
only once. 

4 Flush all files and all input and output 


of pipes and devices. Spin until flushed. 


5 Flush all files and all input and output 
of pipes and devices. Flush only once. 


The default is 0. 


This heuristic gives the requester application 
more flexibility as to which files, pipes, or 
devices are flushed (written to disk) when 
DosBufReset or DosClose is done. 


Used to support OS/2 LAN Server encryption. 
The default is 1. 


Control log entries for multiple occurrences of an 
error. A recurring error can fill up the error log; 
use this heuristic to keep down the number of 
log entries. If the value is other than 0, the first, 
fourth, eighth, 16th, and 32nd occurrences of an 
error are logged. After that, every 32nd further 
occurrence is logged. 


If the value is other than 0, it also defines the 
size of an error table. The table is a record of 
what errors have occurred. If an error does not 


23 


24 


match an existing entry in the table, it replaces 
the entry with the lowest number of occurrences. 


Set the value as follows: 


Value Meaning 


0 Log all occurrences 

1 Use error table, size 1 
2 Use error table, size 2 
3 Use error table, size 3 
4 Use error table, size 4 
5 Use error table, size 5 
6 Use error table, size 6 
7 Use error table, size 7 
8 Use error table, size 8 
9 Use error table, size 9. 
The default is 0. 


Buffer all files opened with deny-write sharing 
mode. The default is 1. 


When this heuristic is active, the server buffers 
all files opened with deny-write sharing mode, 
even if the access mode is not read-only. 


This heuristic deactivates buffering on this 
requester if an application does not work 
correctly with it. 


Buffer all files opened with read only access. 
The default is 1. 


When this heuristic is active, the server buffers 
all files opened with read-only access mode, even 
if the sharing mode is not deny-write. 


This heuristic deactivates buffering on this 
requester if an application does not work 
correctly with it. 
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25 


26 


oa 


28 


29 


Read ahead when opening for execution. 
Reading an executable file sequentially is usually, 
but not always, faster. The default is 1. 


This heuristic value should be 1 for many 
executable files loaded across the LAN. For 
example, DisplayWrite™ 4/2 load time decreases 
by more than 50 percent. Experiment with your 
particular program to determine which option is 
better. 


Handle Control-C (Ctri+(C) as follows: 


Value Meaning 


0 No interrupts allowed 

1 Only allow interrupts on long-term 
operations 

Z Always allow interrupts. 

The default is 2. 


Force correct open mode when creating files on 
a core server. (A core server is a DOS-based 
LAN server, such as PC LAN Program 1.3.) 
OS/2 LAN Server does not allow DOS-based 
servers. The default is 0. 


Use the NETBIOS NoAck mode (transferring 
data without waiting for an acknowledgement) 
as follows: 


Value Meaning 
0 NoAck is never used (disable NoAck) 
j NoAck on send only. 


The default is 1. 


Send data along with the server message block 
write block raw requests. This may save time. 
The default is 1. 


When this heuristic is active, the requester sends 
a requester buffer of data to the server with its 
request for big buffers to use for large file 
transfers. This action may save time if the server 
has limited big buffers (numbigbufs) compared to 
the number of requesters trying to send large 
files. 


DisplayWrite is a trademark of International Business Machines Corporation. 
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30 Send a popup message to the screen when the 
requester logs an error, as follows: 


Value Meaning 


0 Never 
l On write fault errors only (no timeout) 
Zz On write fault and internal errors only 


(no timeout) 


3 On all errors (no timeout) 

4 Reserved. 

5 On write fault errors only (timeout) 

6 On write fault and internal errors only 
(timeout) 

7 On all errors (timeout). 


The default is 1. 


Values other than 1 are normally used for debug 
purposes only. 


31 Reserved. 


wrknets Lists names of networks the requester runs on. Names 
of available networks are listed in the Networks section 
of the IBMLAN.INI file. The OS/2 LAN Server 
supports only a single network. 


Required value: netl 


wrkservices Specifies network services to start with the Requester 
service. For example, the Messenger service, which 
sends and receives network messages, can be started 
with the Requester service. The options are Messenger 
and Netpopup. This value is defined by the user at 
installation. 


¢ wki0_mailslots specifies the maximum number of mailslots allowed. 
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Requester Information (Level 1) 
Requester information level 1 includes all the fields of wksta_info_0, plus 
oth_domains and logon_domains. 


struct wksta_info_1 { 
unsigned short wkil_reserved_1; 
unsigned long wkil_reserved_2; 
* 


char far wkil_root; 

char far * wkil_computername; 
char far * wkil_username; 
char far * wkil_langroup; 


unsigned char wkil_ver_major; 
unsigned char wkil_ver_minor; 
unsigned long wkil_reserved_3; 
unsigned short wkil_charwait; 
unsigned long wkil_chartime; 
unsigned short wkil_charcount; 
unsigned short wkil_reserved_4; 
unsigned short wkil_reserved_5; 
unsigned short wkil_keepconn; 
unsigned short wkil_keepsearch; 
unsigned short wkil_maxthreads; 
unsigned short wkil_maxcmds; 
unsigned short wkil_reserved_6; 
unsigned short wkil_numworkbuf; 
unsigned short wkil_sizworkbuf; 
unsigned short wkil_maxwrkcache; 
unsigned short wkil_sesstimeout; 
unsigned short wkil_sizerror; 
unsigned short wkil_numalerts; 
unsigned short wkil_numservices; 
unsigned short wkil_errlogsz; 
unsigned short wkil_printbuftime; 
unsigned short wkil_numcharbuf; 
unsigned short wkil_sizcharbuf; 


char far * wkil_logon_server; 
char far * wkil_wrkheuristics; 
unsigned short wkil_mailslots; 
char far * wkil_logon_domain; 
char far * wkil_oth_domains; 
unsigned short wkil_numdgrambuf; 

}; 

where: 


¢ wkil_reserved_1, wkil_reserved_2, wkil_reserved_3, wkil_reserved_4, 
wkil_reserved_5, and wkil_reserved_6 are reserved, and must be 0. 


¢ wkil_root points to an ASCIIZ string containing the path to the IBMLAN 
directory (the recommended default path is IBMLAN\) of a computer . 


¢ wkil_computername points to an ASCIIZ string containing the computer name 
of the local requester being configured. 


e wkil_username points to an ASCIIZ string containing the user’s name logged on 
the requester. 


e wkil_langroup points to an ASCIIZ string containing the name of the domain to 
which the requester belongs. 
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wkil_ver_major specifies the major version number of the OS/2 LAN 
Requester/Server software running on the computer. 


wkil_ver_minor specifies the minor version number of the OS/2 LAN 
Requester/Server software running on the computer. 


wkil_charwait indicates the number of seconds the requester will wait for a 
remote serial device resource to become available. 


wkil_chartime indicates the number of milliseconds the requester will wait to 
collect data to send to a remote serial device resource. 


wkil_charcount indicates the number of bytes of information the requester will 
send to a remote serial device resource. 


wkil_keepconn indicates the number of seconds an inactive connection from the 
requester to the resource a server will be maintained. 


wkil_keepsearch indicates the number of seconds an inactive search will 
continue. 


wkil_maxthreads indicates the number of threads the requester can dedicate to 
the network. 


wkil_maxcmds indicates the number of simultaneous network device driver 
commands that can be sent to the network. 


wkil_numworkbuf indicates the number of internal buffers the requester has. 
wkil_sizworkbuf indicates the size (in bytes) of each internal buffer. 


wkil_maxwrkcache indicates the maximum size (in bytes) of an internal cache 
buffer. 


wkil_sesstimeout indicates the number of seconds that are waited before 
disconnecting an inactive session between a requester and a server. 


wkil_sizerror indicates the size (in bytes) of an internal error buffer. 


wkil_numalerts indicates the maximum number of clients that can receive alert 
messages. 


Note that each mailslot or semaphore registered by the NetAlertStart function is 
a different client, and that the alerter service registers at least three clients when 
it begins to run. For more information on alerts, see “Alert Category” on 

page 3-29. 


wkil_numservices indicates the number of services that can be started on the 
requester at any time. For more information on services, see “Service Category” 
on page 3-298. 


wkil_errlogsz indicates the maximum size (in kilobytes) of the error log file of a 
requester. 


wkil_printbuftime indicates the number of seconds that are waited before closing 
inactive compatibility-mode print jobs. 


wkil_numcharbuf indicates the number of character pipe buffers and device 
buffers the requester can have. 


wkil_sizcharbuf indicates the maximum size (in bytes) of a character pipe buffer 
and device buffer. 
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¢ wkil_logon_server points to an ASCIIZ string indicating the name of the 
Domain Controller of a requester. A NULL string indicates no logon servers 
are available. If the string is \\*, any available logon server is queried. 


¢ wkil_wrkheuristics points to an ASCIIZ string of flags used to control a 
requester operation. The heuristics default to values that are optimal for most 
configurations and normally need not be changed. For character positions and 
meanings, refer to “Requester Information (Level 0).” 


¢ wkil_mailslots specifies the maximum number of mailslots allowed. 


¢ wkil_logon_domains names the domain to which the user is logged on. It is 
returned as NULL when no one is logged on. 


¢ wkil_oth_domains field is an ASCIIZ string listing all domains on which the 
machine is currently enlisted. This is a far pointer to an ASCIIZ string which is 
a space-delimited list of domains. The oth_domains field is settable with 
NetWkstaSetInfo. 


¢ wkil_numdgrambuf is the number of buffers allocated for receiving datagrams. 
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Requester Information (Level 10) 
The wksta_info_10 data structure is supplied to fulfill the needs of remote users who 
want to obtain certain information from a server. This data structure allows remote 
users to discover what domain a server belongs to. 


Since a remote NetWkstaGetInfo at levels 0 and 1 requires administrative privilege, 
a remote user who does not have privilege level ADMIN cannot use those structures. 
This new level provides the needed information. 


struct wksta_info_ 10 { 


ie 


char far * 
char far * 
char far * 
unsigned char 
unsigned char 
char far * 
char far * 


where: 


DOS Considerations 


wki10_computername; 
wki10_username; 
wki10_langroup; 
wki10_ver_major; 
wki10_ver_minor; 
wki10_logon_domain; 
wkil0_oth_domains; 


wkil0_computername points to an ASCIIZ string containing the computer name 
of the requester being queried. 


wkil0_username points to an ASCIIZ string containing the user’s name logged 
on the requester. 


wkil0_langroup points to an ASCIIZ string containing the name of the domain 
to which the requester belongs. 


wkil0_ver_major specifies the major version number of the OS/2 LAN 
Requester/Server software running on the computer. 


wkil0_ver_minor specifies the minor version number of the OS/2 LAN 
Requester/Server software running on the computer. 


wkil0_logon_domain names the domain that the user is logged on to. It is 
returned as NULL when no one is logged on. 


wkil0_oth_domains field is an ASCIIZ string listing all domains on which the 
machine is currently enlisted. This is a far pointer to an ASCIIZ string which is 
a space-delimited list of domains. 


For information on the DOS LAN Requester heuristics, see the DOS LAN Requester 
User’s Guide. 
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Related Information 
For information on: 


* Configuring requesters—See the [BM Operating System/2 Local Area Network 
Server Version 1.2 Network Administrator's Guide. 


¢ The IBMLAN_INI file—See the JBM Operating System/2 Local Area Network 
Server Version 1.2 Network Administrator's Guide. 


¢ Domains—See the IBM Operating System/2 Local Area Network Server Version 
1.2 Network Administrator's Guide. 


¢ NCB architecture—See the JBM PC LAN Program 1.3 Application Programmer's 
Guide. 


¢ wksta_info_0 components—See the JBM Operating System/2 Local Area Network 
Server Version 1.2 Network Administrator's Guide. 
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NetWkstaGetinfo 


The NetWkstaGetInfo (partially admin, DOS) function returns information about 
the configuration components of a requester. 


Syntax 


#include <netcons.h> 
#include <wksta.h> 


unsigned far pascal 
NetWkstaGetInfo(servername, level, buf, buflen, totalavail) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ level specifies the level of detail (0, 1 or 10) to be returned in the wksta_info data 
structure. 


¢ buf points to the wksta_info data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR INVALID _PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR _NetNotStarted | 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_BufTooSmall 


NERR_OS82IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 


Value 
2104 


2123 


2134 


2138 


2139 


2140 


2141 


2351 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


e¢ DosFsRamSemClear 


¢ DosFreeSeg 


¢ DosFsCthNETTRANSACTION) 
¢ DosFsCthNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 


¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 


Remarks 


The ordinary user can get information from the level 10 data structure. 


Related Information 
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For information on modifying the configuration of a local requester, see 
“NetWkstaSetInfo” on page 3-227. 


NetWkstaSetinfo 


Syntax 


The NetWkstaSetInfo (admin, DOS) function configures a requester. 


#include <netcons.h> 
#include <wksta.h> 


unsigned far pascal 
NetWkstaSetInfo(servername, level, buffer, buflen, parmnum) 
char far * servername; 


short level; 
char far * buf; 
unsigned short buflen; 
short parmnum; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


e level specifies the level of detail (0 or 1) returned in the wksta_info data 
structure. 


¢ buf points to the wksta_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines whether buf contains a complete wksta_info data structure 
or a single data structure component. If parmnum is 0, buf must contain a 
complete wksta_info data structure. Otherwise, parmnum must specify the 
ordinal position value for one of the following wksta_info data structure 
components, as defined as follows in WKSTA.H: 


Manifest Value Component 
WKSTA_CHARWAIT_PARMNUM 10 wkix_charwait 
WKSTA_CHARTIME PARMNUM 11 wkix_chartime 
WKSTA_CHARCOUNT_PARMNUM 12 wkix_charcount 
WKSTA_ERRLOGSZ_PARMNUM 2) wkix_errlogsz 
WKSTA_PRINTBUFTIME_PARMNUM 28 wkix_printbuftime 
WKSTA_WRKHEURISTICS_PARMNUM 32 wkix_wrkheuristics 
WKSTA_OTHDOMAINS PARMNUM 35 wkix_oth_domains 


Note: x = Oor l. 
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Return Codes 


_Manifest 
NERR_SUCCESS 


ERROR_ACCESS DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_REM_NOT LIST 


ERROR_INVALID_PARAMETER 


ERROR_INVALID_NAME 


ERROR_INVALID_LEVEL 


ERROR_MORE_ DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_NoNetworkResource 


NERR_BufTooSmall 


NERR_OS2IoctlError 


-NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 
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Value 


51 


87 


123 


124 


234 


2102 


2104 


2105 


2123 


2134 


2138 


2139 


2140 


2141 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


This remote computer 
is not listening. 


The specified 
parameter is invalid. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


A network resource 
shortage occurred. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


Manifest 
NERR InvalidAPI 


NERR_NameNotFound 


NERR AlreadyExists 


NERR_TooManyNames 


NERR_DuplicateName 


NERR_DeleteLater 


NERR_InvalidComputer 


Value 
2142 


2273 


2276 


2277 


2297 


2298 


2351 


Meaning 


The requested API is 
not supported on the 
remote server. 


The message alias 
cannot be found on the 
local area network. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


A duplicate message 
alias exists on the local 
area network. 


This message alias will 
be deleted later. 


The specified computer 
name is invalid. 
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Other error return codes may be returned from the following OS/2 functions: 
¢ DosDevlOCtl 

¢ DosFSCtl 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCth(NETTRANSACTION) 

¢ DosFsCtlhONULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear 

¢ redir.GetBiosInfo[-ERROR_NO_ MORE _ FILES] 
¢ redir.NIOCBiosOpen. 


Remarks 


The fields wki0_computername, wki0_langroup, are not settable by users or 
administrators. 


The values of the field oth_domains in the wksta_info data structure are separated by 
spaces. An empty list is legal. As usual a NULL pointer means “do not modify this 
field.” An empty element is not legal. When setting oth_domains, the API will reject 
the request in the following cases: 


e The name list was incorrect 


¢ One of the names could not be added to the network adapters managed by OS/2 
LAN Requester/Server. 


Related Information 
For information on retrieving the comfiguration of a local requester, see 
“NetWkstaGetInfo” on page 3-225. 
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NetWkstaSetUID2 
The NetWkstaSetUID2 (DOS) function registers a user name and password with 
the requester and validates the user account. It returns a structure with information 
about the logon. This function takes an optional domain name argument. If it is 
absent, it defaults to the primary domain (wki0_langroup) of the requester. 


Syntax 


#include <netcons.h> 
#include <wksta.h> 
#include <access.h> 


unsigned far pascal 
NetWkstaSetUID2(reserved,domainname, username, password, parms, 
ucond, level, buf, buflen, totalavail) 


char far * reserved; 
char far * domainname; 
char far * username; 
char far * password; 
char far * parms ; 
unsigned short ucond; 
short level; 
char far * buf ; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 
e reserved is a reserved parameter, it must be NULL. 


¢ domainname is the name of the domain to log on to. If this parameter is NULL 
or if it points to a NULL string, the primary domain of the requester is used. 


¢ username points to an ASCIIZ string containing the user name to be logged onto 
the requester. Specifying a NULL string logs the user name off the requester. 


e password points to an ASCIIZ string containing the password of the user name, 
obtained by an application’s request to the user. A NULL pointer or string 
indicates no password is needed. password becomes the default password for 
requester and is used whenever the requester attempts to access a remote 
resource. 


¢ parms must be NULL and is reserved. 

e ucond specifies what action to take if another user name is logged on the 
requester. The WKSTA.H include file defines four values: 
Manifest Value Meaning 


WKSTA_NOFORCE 0 NetWkstaSetUID2 fails, and the 
user’s identification number 
(UID) does not change. 


WKSTA_FORCE 1 Logs the current user name off, 
disconnecting any connections to 
redirected resources. 
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Manifest Value Meaning 


WKSTA_LOTS_OF_FORCE z Cancels any connections and 
other pending activities 
necessary. Fails if any 
connection is used by a process 
as the current drive. 


WKSTA_MAX_FORCE 3 Always succeeds—forces all 
disconnections. 


¢ Jevel level of data structure to return. It must be 1. 


¢ buf is the pointer to the buffer user_logon_info_1 or user_logoff_info_1 for return 
data. See the data structures under “User Category” on page 3-382. 


¢ buflen is the length of the buffer. 


e totalavail is the total information available on return. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
VALIDATED_LOGON 1 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_REM_NOT_LIST 51 This remote computer 
is not listening. 
ERROR_INVALID_PASSWORD 86 The specified password 
is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_NAME 123 There is an incorrect 


character or incorrectly 
formed file system 


name. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


3-232 LAN Server Application Programmer’s Reference 


Manifest 
NERR_NetNotStarted 


NERR_ShareMem 


NERR_NoNetworkResource 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_NetworkError 
NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _ InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR _ AlreadyLoggedOn 
NERR_NotLoggedOn 


NERR_BadUsername 


NERR_BadPassword 


NERR_UnableToAddName_W 


Value 
2102 


2104 


2105 


2106 


2123 


2134 


2136 


2138 


2139 


2140 


2141 


2142 


2200 


2201 


2202 


2203 


2204 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


A network resource 
shortage occurred. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


A general network 
error has occurred. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


This workstation is 
already logged on. 


This workstation has 
not been logged on yet. 


The user name or 
group name parameter 
is invalid. 


The password 
parameter is invalid. 


The logon processor 
did not add the 
message alias. 
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Manifest 
NERR_UnableToAddName_F 


NERR_UnableToDelName_W 


NERR_UnableToDelIName_F 


NERR_LogonsPaused 


NERR_LogonDomainExists 


NERR_UserNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_PasswordTooShort 
NERR_InvalidDatabase 


NERR_NameNotFound 


NERR AlreadyExists 


NERR_TooManyNames 


NERR_DuplicateName 


NERR_DeleteLater 


NERR_InvalidComputer 
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Value 
2205 


2206 


2207 


2209 


2216 


2221 


2226 


2221 


2229 


2245 


2247 


2273 


2276 


2277 


2297 


2298 


2351 


Meaning 


The logon processor 
did not add the 
message alias. 


The logoff processor 
did not delete the 
message alias. 


The logoff processor 
did not delete the 
message alias. 


The network logons 
are paused. 


There is already a 
logon domain for this 
computer. 


The user name cannot 
be found. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The password is 
shorter than required. 


The UAS database file 
is corrupted. 


The message alias 
cannot be found on the 
local area network. 


This message alias 
already exists locally. 


The maximum number 
of added message 
aliases has been 
exceeded. 


A duplicate message 
alias exists on the local 
area network. 


This message alias will 
be deleted later. 


The specified computer 
name is invalid. 


Manifest Value Meaning 


NERR_ActiveConns 2402 Active connections still 
exist. 
NERR_LastAdmin 2452 The last administrator 
cannot be deleted. 
NERR _LogonTrackingError 2454 Unable to set logon 
information for this 
user. 
NERR_NetLogonNotStarted 2455 The Netlogon service 
has not been started. 
NERR_CanNotGrowUASFile 2456 It is not possible to 


grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCth(NETTRANSACTION) 

¢ DosFsCthNIOCGETUSERNAME) 

¢ DosFsCtlh(NIOCSETUSERNAME) 

¢ DosFsCthNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize[-ERROR_DISK_FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 

¢ DosWrite 

¢ int2F[2F_NetSetUserName]/*DOS only*/ 

e redir.GetBiosInfo[-ERROR_NO_MORE_FILES] 
e redir.NIOCBiosOpen 

¢ redir.NIOCGetUserName 

e redir.NIOCSetUserName. 
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Remarks 
The NetWkstaSetUID2 function performs a range of duties, assisted by. internal 
calls. It returns a structure with information about the logon (user_logon_info: 1) or 
the logoff (user_logoff_info: 1). 


If a user name is already logged onto the requester (UID already in effect), 
NetWkstaSetUID2 takes the action specified in ucond—either failing or forcing the | 
user to log off. 


A NULL user name is interpreted as a network logoff. 


If the user’s logon is invalid, the API returns ERROR_ACCESS_ DENIED. The 
usrlog1_code code field in the user_logon_info_1 data structure is valid even when the 
API returns ERROR_ACCESS_ DENIED. The other fields are valid only when the 
return code is Validated Logon. 


The values of the usrlog/code fields can be as follows: 


Manifest Meaning 
NERR_Success No errors were encountered. 
NERR_PasswordExpired The user has an account, but the user’s 


password has expired. No other 
conditions of logon have been checked. 


NERR_InvalidWorkstation The user was attempting to log on from 
an invalid requester. 

NERR _ InvalidLogonHours: The user was attempting to log on at an 
invalid time. 

ERROR_ACCESS_DENIED Some condition of logon has not been 
met. 

NERR_StandaloneLogon No domain controller could be found to 


validate the user. Script processing was 
not performed. 


NERR_NonValidatedLogon The logon server could not validate the 
logon request. 


NERR_LogonScriptError An error occurred while processing 
logon script. 


The following table defines the other fields that are valid in the user_logon_info_1 
data structure for each code listed in the previous table: 


Error Returned from Manifest Logon Valid 
NetWkstaSetUID2. Fields. 
NERR_ Success. NERR_Standalone None 
NERR_UnableToAddName_W NERR_NonValidatedLogon Computer 
name, 
Script 
path 
NERR_Success All 
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Error Returned from Manifest Logon Valid 
NetWkstaSetUID2 Fields 
ERROR_ACCESS_ DENIED NERR_PasswordExpired None 
NERR_InvalidWorkstation None 
NERR_InvalidLogonHours None 
NERR _LogonScriptError None 
ERROR_ACCESS_DENIED(**) None 
Ail other errors None. Code is meaningless None 


(**) For no account, account disable, and account expired, the password does not 
match. 


The following table defines fields for logging off: 


Error Returned from Manifest Logon Valid 
NetWkstaSetUID2 Fields 
NERR _Success NERR StandaloneLogon None 
NERR_UnableToDelName_W NERR_NonValidatedLogon None 
NERR Success All 
All other errors None. Code is meaningless None 


Related Information 


The ucond parameter has meaning only when the API is called to log someone off. 
These meanings are as follows: 


Check all ucond = 0 ucond = 1 ucond = 2 ucond = 3 
outstanding 
conditions 
1)Any drive Fail. Do no Fail. Do no Fail. Do no Force 
current disconnects. disconnects. disconnects. disconnect 
succeed. 
2) Any drive Fail. Do no Fail. Do no Force closed, Force closed, 
disconnects. disconnects. succeed. succeed. 
3) Any in use Fail. Do no Disconnect, Disconnect, Disconnect, 
(net use..) disconnects. Unuse, Unuse, Unuse, 
succeed. succeed. succeed. 
4) Anything Disconnect Disconnect Disconnect Disconnect 
dormant and succeed. and succeed. and succeed. and succeed. 


For information on configuring the local requester, see “NetWkstaSetInfo” on 


page 3-227. 
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Serial Device Category 
NetCharDevControl (admin, server, DOS)—See “NetCharDevControl” on page 3-243. 


NetCharDevEnum (admin, server, DOS)—See “NetCharDevEnum” on page 3-246. 
NetCharDevGetInfo (server, DOS)—See “NetCharDevGetInfo” on page 3-248. 
NetCharDevQEnum (server, DOS)—See “NetCharDevQEnum” on page 3-251. 
NetCharDevQGetInfo (server, DOS)—See “NetCharDevQGetInfo” on page 3-254. 
NetCharDevQPurge (admin, server, DOS)—See “NetCharDevQPurge” on page 3-257. 


NetCharDevQPurgeSelf (server, DOS)—See “NetCharDevQPurgeSelf” on 
page 3-260. 


NetCharDevQSetInfo (admin, server, DOS)—See “NetCharDevQSetInfo” on 
page 3-263. 


The functions in the Serial Device category control shared serial devices and their 
associated queues. They are used with the CHARDEV.H and NETCONS.H include 
files. 


Description 
In order for an application to communicate with a device such as a serial printer, the 
application must be able to communicate directly and interactively. The 
communication must allow commands to be submitted dynamically and protocols to 
be changed as the application executes. The OS/2 LAN Requester/Server software 
defines these types of communication devices as serial devices. This definition is not 
limited to devices attached to a hardware serial ports. 


The OS/2 LAN Requester/Server software can pool serial devices of the same type 
into a serial device queue to which a requesting application makes its connection. A 
serial device queue can contain one or more serial devices and simultaneously allow 
multiple applications to individually connect to one of the available serial devices. 
Serial device queues can pool serial devices only on a server. 


Before an application can communicate with a serial device, the following must 
occur: 


e The server must have a serial device connected to one of its available LPT or 
COM ports. 


e A serial device queue must be created and shared on the network. 


e A requesting application must explicitly redirect a local or NULL device name 
to the shared serial device queue by calling NetUseAdd, or implicitly open the 
serial device queue by calling DosOpen. 


Note: Serial device queues exist only while they are being shared. In contrast, a 
spooled device queue (such as for a printer) exists from the time it is created 
by calling the appropriate Add function to the time it is removed. 


An application can explicitly redirect a local device name in order to connect to a 


serial device queue by calling the NetUseAdd function, or implicitly connect by 
calling the DosOpen function and specifying the name of a queue. An explicit 
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connection allows the application to refer to the serial device queue with a local 
device name. Note however, that an explicit connection does not open a serial 
device. For more information about redirecting a local device name to a shared 
resource, see “Use Category” on page 3-368. 


To illustrate how serial devices and queues work on the LAN, consider the following 
scenario. Assume that there are four serial devices connected to the communication 
ports of a server in the following manner: 


Port Device 
COM1, COM2, COM3 Printers 
COM4 Special 


Once the serial devices are connected to the ports of a servers, an application can 
create a serial device queue by calling the NetShareAdd function and specifying the 
share type as a serial device queue. In this scenario, assume the NetShareAdd 
function is called three times, creating the following three queues: 


Queue name Priority Device name 

SPLQ 5 COM4 

PRINTQ 5 COM1, COM2, COM3 
VIPPRINT 1 COM3 


Note that the COM3 port is allocated for use by two different queues, PRINTQ and 
VIPPRINT. After the NetShareAdd function is called to create a queue, a 
parameter can be set assigning a priority to the queue by calling 
NetCharDevQSetInfo. The priority can be in the range from 1 (high) through 9 
(low). Generally, the OS/2 LAN Requester/Server software allows requests to serial 
device queues with a higher priority to access the pool of serial devices before other 
queues with lower priorities. 


At this point, an application can connect to the shared serial device queue and begin 
communicating with one of the pooled serial devices in the queue. 


If there happens to be more than one available serial device in a serial device queue, 
the queue returns the first available serial device to the requesting application. If no 
devices are currently available, the queue puts the request on a waiting list until a 
serial device becomes available. Note that the queue will wait only as long as the 
charwait parameter of a requester specifies. If the thread undergoes a time out while 
waiting for a serial device to become available, the DosOpen function returns the 
ERROR_BAD_NET_RESP error code. 


An application can determine if a particular serial device is working by calling the 
NetCharDevGetInfo function or check all devices by calling the NetCharDevEnum 
function. An application can also check to see if the queue is busy or where the 
request of the application is on the queue waiting list by calling the 
NetCharDevQGetInfo function. To check all queues, call the NetCharDevQEnum 
function. 


Applications can call the NetCharDevQPurgeSelf function to eliminate all requests 


submitted to a particular serial device queue from the requester of that application. 
Or, all requests submitted by all applications can be removed from the queue by 
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calling NetCharDevQPurge. Note that a process that currently has a device open is 
unaffected. 


When the application no longer needs the device, it should call the DosClose 
function to return control of the serial device to the serial device queue, allowing it 
to be used by another application. If, for some reason, the application cannot 
successfully call the DosClose function to close the serial device queue, the 
NetCharDevControl function can be called to force the serial device queue closed. 


Note that when an application successfully opens a remote serial device, the values 
of the chartime and charcount components from the wksta_info data structure are 
used to control how information flows across the network to other pertinent 
requesters and servers. Any application modifying these values on the requester 
where the open was performed should note the following: 


¢ chartime and charcount affect all applications running on the requester 


¢ Network efficiency, network response time, and network throughput may be 
slowed. 


For more information on requester parameters, see “Requester Category” on 
page 3-208. 


Data Structures 
The /evel parameter controls the level of information provided to or returned from 
the data structures used by the NetCharDevEnum, NetCharDevGetInfo, 
NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo functions. 


Serial Device Information (Level 0) 
The NetCharDevEnum and NetCharDevGetInfo functions use the following data 
structure when the /evel parameter is 0: 


struct chardev_info_0 { 
char ch0_dev[DEVLEN+1]; 
}; 


where: 


¢ ch0_dev is an ASCIIZ string containing the device name associated with the 
serial device. 


Serial Device Queues Information (Level 0) 
The NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo 
functions use the following data structure when the Jevel parameter is 0: 


struct chardevQ_info_0 { 
char cq0_dev[NNLEN+1]; 
}3 


where: 


¢ cq0_dey is an ASCIIZ string containing the queue name for the serial device 
queue. 
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Serial Device Information (Level 1) 
The NetCharDevEnum and NetCharDevGetInfo functions use the following data 
structure when the level parameter is 1: 


struct chardev_info_1 { 


char chi_dev[DEVLEN+1] ; 
char chi_pad1; 
unsigned short chl_status; 
char chl_username[UNLEN+1] ; 
char ch1_pad2; 
unsigned long chi_time; 

‘3s 

where: 


¢ chl_dev is an ASCIIZ string specifying the devicename associated with the serial 
device. 


¢ chl_pad] WORD.-aligns the data structure components. 


¢ chl_status specifies the status of the device. ch1_status is defined as follows: 


Bit Meaning 
0 Reserved, with a value of 0. 
1 If 0, the device is idle; if 1, the device is opened, and presumably 


in use by some application. 


2 If 0, the device has encountered no errors; if 1, the device has 
encountered an error. 


3-15 Reserved, with a value of 0. 


¢ chl_username is an ASCIIZ string specifying the current user of the device. 
¢ chl_pad2 WORD-aligns the data structure components. 


¢ chl_time specifies the number of seconds the current application has been 
connected. to the serial device. 


Serial Device Queues Information (Level 1) 
The NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo 
functions use the following data structure when the /evel parameter is 1: 


struct chardevQ_info_1 { 


char cql_dev[NNLEN+1]; 
char cqli_pad; 
unsigned short cql_priority; 
char far * cql_devs; 


unsigned short cql_numusers; 
unsigned short cql1_numahead; 
}; 
where: 
¢ cql_dev is an ASCIIZ string specifying the queue name. 


¢ cql_pad WORD-aligns the data structure components. 
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¢ cql_priority specifies the queue priority. cq/_priority can be in the range from 1 
through 9, where 1 has highest priority. 


¢ cgl_devs points to an ASCIIZ string containing the device names assigned to the 
queue (such as COM1 COM3). 


¢ cql_numusers specifies the number of user names in the queue. 


¢ cql_numahead specifies the number of user names in front of a particular user. 
To find the number of users, specify username with the NetCharDevQEnum or 
NetCharDEvQGetInfo function. If cqg]_numahead is -1, then username is not 
currently in the queue. 
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NetCharDevControl 


Syntax 


Return Codes 


The NetCharDevControl (admin, server, DOS) function forces a serial device closed. 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 

NetCharDevControl (servername, devname, opcode) 
char far * servername; 

char far * devname; 

short opcode; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ devname points to an ASCIIZ string specifying the device to modify. 
¢ opcode specifies how to modify devname. opcode is defined in CHARDEV.H as 


follows: 
Manifest Value Meaning 
CHARDEV_CLOSE 0 Closes the serial device 
Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 
ERROR_SEM_TIMEOUT 121 A time out happened 
from the semaphore 
API functions. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 
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Manifest 


NERR_RemoteOnly 


‘NERR_ServerNotStarted 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_DevInvalidOpCode 


NERR_DevNotFound 


NERR_DevNotOpen 


NERR_NoCommDevs 


NERR_InvalidComputer 
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Value 


2106 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2331 


2332 


2333 


2337 


2351 


Meaning 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The operation is 
invalid for this device. 


This device cannot be 
shared. 


This device was not 
open. 
There are no shared 


communication 
devices. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFSRamSemClear 

DosFsRamSemClear 

DosFreeSeg 

DosFsCthKNETTRANSACTION) 
DosFsCth(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosSemClear 


DosSem Request. 


Normally, a serial device is closed with a call to the DosClose function. If for some 
reason the process that opened the device cannot close it, NetCharDevControl can 
be called to force the device closed. 


Related Information 


For information on: 


Modifying a serial device queue—See “NetCharDevQSetInfo” on page 3-263. 


Retrieving information about a serial device—See “NetCharDevGetInfo” on 
page 3-248. 


Retrieving information about a serial device queue—See “NetCharDevQGetInfo” 
on page 3-254. 
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NetCharDevEnum 


The NetCharDevEnum (admin, server, DOS) function provides information on all 
available serial devices pooled in shared serial device queues on a server. 


Syntax 
#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetCharDevEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ level specifies the level of detail (0 or 1) requested for the returned chardev_info 
data structure. 


¢ buf points to the chardev_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR _ ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR _NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE_ DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest Value Meaning 


NERR_ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 

NERR ServerNotStarted 2114 The Server service has 
not been started. 

NERR_OS2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 


NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 


NERR _InternalError 2140 An internal error has 
occurred. 


NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 


NERR_NoCommDevs 2337 There are no shared 
communication 
devices. 


NERR _InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCtlh(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 


Related Information 
For information on: 


e Enum functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 


e Listing serial device queues on a server—See “NetCharDevQEnum” on 
page 3-251. 
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NetCharDevGetinfo 


The NetCharDevGetInfo (server, DOS) function retrieves information about a 
particular serial device in a shared serial device queue on a server. 


Syntax 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 


NetCharDevGetInfo(servername, devname, level, buf, 


buflen, totalavail) 


char far * servername; 
char far * devname; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 


where: 


* servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


server. 


¢ deyname points to an ASCIIZ string containing the name of a serial device. 


¢ level specifies the level of detail (0 or 1) requested for the returned chardev_info 


data structure. 


¢ buf points to the chardev_info data structure. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 


information that were available. 
Return Codes 
Manifest 
NERR_ SUCCESS 
ERROR_ACCESS_ DENIED 
ERROR_NOT_ENOUGH_ MEMORY 
ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


NERR_NetNotStarted 
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Value 


87 


124 


2102 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 
Sufficient memory is 
not available. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


The redirector 
NETWKSTA.EXE has 
not been started. 


Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_ WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_DevNotFound 


NERR_NoCommDevs 


NERR InvalidComputer 


Value 


2104 


2106 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2a32 


2337 


2351 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


This device cannot be 
shared. 


There are no shared 
communication 
devices. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


e DosFreeSeg 


DosFsCth(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 
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Remarks 
A device can belong to more than one queue. 


Related Information 
For information on: 


¢ GetInfo functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 
e Listing all serial device queues—See “NetCharDevEnum” on page 3-246. 


¢ Modifying the state of a serial device—See “NetCharDevControl” on 
page 3-243. 


3-250 LAN Server Application Programmer’s Reference 


NetCharDevQEnum 


Syntax 


Return Codes 


The NetCharDevQEnum (server, DOS) function enumerates all serial device queues 
on a server. 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetCharDevQEnum(servername, username, level, buf, 
buflen, entriesread, totalentries) 


char far * servername; 
char far * username; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ username points to an ASCIIZ string containing a user name. username can be 
used to calculate how many requests are pending ahead in the queue by 
examining the cq/_numahead parameter. 


¢ level specifies the level of detail (0 or 1) requested for the chardevQ_info data 
structure. 


¢ buf points to the returned chardevQ_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Manifest Value Meaning 

NERR_ SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 

ERROR_INVALID PARAMETER 87 The specified 
parameter is invalid. 

ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR_MORE_ DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR _ ServerNotStarted 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_NoCommDevs 


NERR InvalidComputer 


Value. 


234 


2102 


2104 


2106 


2114 


2134 


2138 


2139 


2140 


2141 


2337 


2351 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


An internal error 
occurred when calling 
the workstation driver.. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


There are no shared 
communication 
devices. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


e DosFSRamClear 
¢ DosFreeSeg 


DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 
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Related Information 
For information on: 


e Deleting the contents of a serial device queue—See “NetCharDevQPurge” on 
page 3-257. 


e¢ Enum functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 


e Listing serial devices on a server—See “NetCharDevEnum” on page 3-246. 
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NetCharDevQGetinfo 


The NetCharDevQGetInfo (server, DOS) function retrieves information about a 
particular serial device queue on a server. 


Syntax 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetCharDevQGetInfo(servername, queuename, username, level, 
buf, buflen, totalavail) 


char far * servername; 
char far * queuename; 
char far * username; 
short level; 

char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ queuename points to an ASCIIZ string containing the name of the serial device 
queue for which information is being requested. 


° username points to an ASCIIZ string specifying the name of a user. username 
can be used to calculate how many requests are pending ahead in the queue by 
examining the cq/_numahead parameter. 


e level is a short integer specifying the level of detail (0 or 1) requested for the 
chardevQ_info data structure. 


¢ buf points to the chardevQ_info data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 


parameter is invalid. 
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Manifest 
ERROR INVALID NAME 


ERROR _INVALID_LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_BufTooSmail 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_BadUsername 


NERR_ NoCommDevs 


NERR_QueueNotFound 


NERR_InvalidComputer 


Value 
123 


124 


234 


2102 


2104 


2106 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2202 


2531 


2338 


2351 


Meaning 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The user name or 
group name parameter 
is invalid. 


The user does not 
belong to this group. 


A queue does not exist 
for this request. 


The specified computer 
name is invalid. 
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Other error return codes may be returned from the following OS/2 functions: 


Related Information 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


For information on: 


GetInfo functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 


Listing serial device queues on a server—See “NetCharDevQEnum” on 
page 3-251. 


Modifying the state of a serial device queue—See “NetCharDevQSetInfo” on 
page 3-263. 
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NetCharDevQPurge 


Syntax 


Return Codes 


The NetCharDevQPurge (admin, server, DOS) function deletes all pending requests 
on a serial device queue. 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetCharDevQPurge(servername, queuename) 
char far * servername; 

char far * queuename; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


© queuename points to an ASCIIZ string containing the name of the queue to 
purge pending requests. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 
ERROR_SEM_TIMEOUT 121 A time out happened 


from the semaphore 
API functions. 


ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR _NetNotStarted 2102 The redirector 


NETWKSTA.EXE has 
not been started. 


NERR_ ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 

NERR ServerNotStarted 2114 The Server service has 


not been started. 
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Remarks 
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Manifest 


~ NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_NoCommDevs 


NERR_QueueNotFound 


NERR_InvalidComputer 


Value 
2123 


2134 


2138 


2139 


2140 


2141 


2142 


2337 


2338 


2351 


Meaning 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


There are no shared 
communication 
devices. 


A queue does not exist 
for this request. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCth(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 


¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear 


¢ DosSemRequest. 


The NetCharDevQPurge function deletes only requests that have not yet been 
assigned to a device. A process that currently has a device open is unaffected. All 
pending requests queued on queuename are canceled, returning the 

ERROR_BAD _NET_RESP error code for each call to the DosOpen function. All 


handles are still valid. 


Related Information 
For information on: 


¢ Closing the current session of a serial device—See “NetCharDevControl” on 
page 3-243. 


¢ Deleting the contents of a serial device queue—See “NetCharDevQPurgeSelf” on 
page 3-260. 


¢ Listing a serial device queues of a server—See “NetCharDevQEnum” on 
page 3-251. 


¢ Modifying the state of a serial device queue—See “NetCharDevQSetInfo” on 
page 3-263. 
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NetCharDevQPurgeSelf 


The NetCharDevQPurgeSelf (server, DOS) function deletes all pending requests 
waiting in a serial device queue that were submitted by a particular computer. 


Syntax 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 


NetCharDevQPurgeSel f(servername, queuename, computername) 


char far * servername; 
char far * queuename; 
char far * computername; 


where: 


* servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


server. 


* queuename points to an ASCIIZ string containing the name of the queue to 


purge queue requests. 


* computername points to an ASCIIZ string specifying the name of a computer 
whose requests are to be deleted from queuename. 


Return Codes 
Manifest 
NERR_SUCCESS 
ERROR_ACCESS_DENIED 
ERROR_NOT_ENOUGH_MEMORY 


ERROR_INVALID_PARAMETER 


ERROR_SEM_TIMEOUT 


ERROR_INVALID_NAME 


ERROR _INVALID_LEVEL 


NERR_NetNotStarted 
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Value 
0 


87 


121 


123 


124 


2102 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 


not available. 


The specified 
parameter is invalid. 


A time out happened 
from the semaphore 
API functions. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


The redirector 
NETWKSTA.EXE has 
not been started. 


Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR _ItemNotFound 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _ InternalError 


NERR_BadUsername 


NERR_NoCommDevs 


NERR_QueueNotFound 


NERR _InvalidComputer 


Value 
2104 


2106 


2114 


2115 


2123 


2134 


2138 


2139 


2140 


2202 


2337 


2338 


2351 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The device queue is 
empty. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The user name or 
group name parameter 
is invalid. 


There are no shared 
communication 
devices. 


A queue does not exist 
for this request. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


DosFsCtlh(CNETTRANSACTION) 
DosFsCth(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosSemClear 


DosSemRequest. 
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Remarks 
The NetCharDevQPurgeSelf function deletes all requests that the NetCharDevPurge 
function specifies, except that only requests from computername are deleted. A 
process that currently has a device open is unaffected. 


Administrative permissions are required to delete requests from other computers 
when NetCharDevQPurgeSelf is called remotely. Administrative permissions are not 
required to delete requests made from the computer of an application. 


Related Information 
For information on: 


e Listing serial device queues on a server—See “NetCharDevQEnum” on 
page 3-251. 


¢ Modifying the state of a serial device queue—See “NetCharDevQSetInfo” on 
page 3-263. 


¢ Deleting the contents of a serial device queue—See “NetCharDevQPurge” on 
page 3-257. 
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NetCharDevQSetinfo 


Syntax 


Return Codes 


The NetCharDevQSetInfo (admin, server, DOS) function modifies the state of a 
serial device queue on a server. 


#include <netcons.h> 
#include <chardev.h> 


unsigned far pascal 
NetCharDevQSetInfo(servername, queuename, level, 
buf, buflen, parmnum) 


char far * servername; 
char far * queuename; 
short level; 
char far * buf; 
unsigned short buflen; 
short parmnum; 
where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ queuename points to an ASCIIZ string containing the name of the serial device 
queue to set. 


¢ level specifies the level of detail (1) supplied to the chardevQ_info data structure. 
¢ buf points to the chardevQ_info data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines whether buf contains a complete chardevQ_info_I data 
structure or a single data structure component. If parmnum is 0, then buf must 
contain a chardevQ_info_1 data structure. Otherwise, parmnum must specify the 
ordinal position value for one of the following data structure components, as 
defined in CHARDEV.H as follows: 


Manifest Value Component 
CHARDEVQ PRIORITY _PARMNUM 2 cql_priority 
CHARDEVQ DEVICES PARMNUM 3 cq1_devs 
Manifest Value Meaning 
NERR_ SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID PARAMETER 87 The specified 


parameter is invalid. 
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Manifest 
ERROR_SEM_TIMEOUT 


ERROR_INVALID_ LEVEL 


ERROR_MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_ServerNotStarted 


NERR_RedirectedPath 


NERR_NoRoom 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 
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Value 
121 


124 


234 


2102 


2104 


2106 


2114 


2117 


2119 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


Meaning 


A time out happened 
from the semaphore 
API functions. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The operation is 
invalid on a redirected 
device. 


The server is currently 
out of the requested 
resource. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested ArI is 
not supported on the 
remote server. 


Manifest 
NERR_UseNotFound 


NERR_BadQueuePriority 


NERR_NoCommDevs 


NERR_QueueNotFound 
NERR_BadDevString 
NERR_BadDev 

NERR InUseBySpooler 


NERR _ InvalidComputer 


Value 
2250 


2335 


2337 


2338 


2340 


2341 


2342 


2351 


Meaning 


The connection cannot 
be found. 


The queue priority is 
invalid. 
There are no shared 


communication 
devices. 


A queue does not exist 
for this request. 


This list. of devices is 
invalid. 


The requested device is 
invalid. 


This device is already 
in use by the spooler. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosDevIOCtl 


¢ DosFsRamSemClear 


e DosFsRamSemRequest 


DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCrl(NIOCGETASGLIST)[-ERROR_NO_MORE FILES] 
DosFsCtl(NULLTRANSACT) 

DosFsCtl(NetGetRdrAddr) 

DosGetShrg 

DosSemClear 

DosSemRequest 

redir. NIOCGETASGLIST1_1[-ERROR_NO_ MORE FILES]. 
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Remarks 


The NetCharDevSetInfo can set the cq/_priority and the cq/_devs components in the 
chardevQ_info_I data structure. 


Related Information 
For information on: 


¢ Deleting the contents of a serial device queue—See “NetCharDevQPurge” on 
page 3-257. 


e Listing serial device queues on a server—See “NetCharDevQEnum” on 
page 3-251. 


¢ SetInfo functions—See Chapter 1, “Overview of OS/2 LAN Server API.” 
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Server Category 


NetServerAdminCommand (admin, server, DOS)—See “NetServerAdminCommand” 
on page 3-284. 


NetServerDiskEnum (admin, DOS)—See “NetServerDiskEnum” on page 3-287. 
NetServerEnum2 (DOS)—See “NetServerEnum2” on page 3-289. 


NetServerGetinfo (partially admin, server, DOS)}—See “NetServerGetInfo” on 
page 3-292. 


NetServerSetInfo (admin, server, DOS)—See “NetServerSetInfo” on page 3-295. 
With the functions in the Server category, an application can perform remote 


administrative tasks on a local or remote server. These functions are used with the 
SERVER.H and NETCONS.H include files. 


DOS Considerations 


Description 


Data Structures 


Under DOS, the functions in the server category enable remote administrative tasks 
to be performed on a remote server. NetServerEnum can be executed on either a 
local requester or remote server; all of the other server functions are executed on a 
remote server. Attempting to execute NetServerAdminCommand or 
NetServerGetInfo on a local requester returns NERR_RemoteOnly. 


Any user or application assigned administrative privileges on a local or remote server 
can perform administrative tasks on that server, controlling its operation, user 
access, and resource sharing. A user can be given such privilege or access by way of 
the NetUserAdd and NetUserSetInfo functions (see “User Category” on 

page 3-382), or the NetShareAdd and NetShareSetInfo functions (see “Share 
Category” on page 3-337). 


Certain low-level parameters affecting the operation of a server, defined in the 
IBMLAN.INI file of the server, can be examined and modified by calling the 
NetServerGetInfo and NetServerSetInfo functions. 


Other changes in the operation of a server require execution of one of the NET 
commands (such as NetUse or NetShare). To execute a Net command on a server, 
an application calls the NetServerAdminCommand function. This function also 
accepts any OS/2 command for execution on the server. 


To obtain a list of servers available to perform remote administration, an application 
calls the NetServerEnum2 function. The NetServerEnum?2 function enumerates the 
set of all servers visible on the network. The type of NetServerEnum2 matches the 
bit mask in the field. To obtain a list of local drives, an application calls the 
NetServerDiskEnum function. 


To set up a server or to reconfigure an existing server, use server_info_1, 
server_info_2, or server_info_3 with NetServerSetInfo. 


NetServerGetInfo returns configuration information at four levels by way of 
server_info_O (server name only), server_info_1, server_info_2. and server_info_3. 
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The lists of server information returned by NetServerEnum2 are limited to level 0 or 
level 1. 


NetServerAdminCommand uses no data structure. 
Server Information (Level 0) 


struct server_info_0 { 

char svO0_name[CNLEN + 1]; 
}; 
where: 


¢ sv0_name is an ASCIIZ string containing the name of a server. 


Server Information (Level 1) 
At level 1, NetServerEnum2, NetServerGetInfo, and NetServerSetInfo use the 
server_info_I data structure. 


struct server_info_1 { 
char svl_name[CNLEN + 1]; 
unsigned char svl_version_major; 
unsigned char svl_version_minor; 
unsigned long svl_type; 
char far * sv1_comment ; 
}; 
where: 
e svi_name is an ASCIIZ string containing the name of a server. 


¢ svJ_version_major is the major release version number of the OS/2 LAN 
Requester/Server software. 


¢ svl_version_minor is the minor release version number of the OS/2 LAN 
Requester/Server software. 


¢ svl_type indicates the type of software the computer is running, defined in 


SERVER.H as follows: 
Manifest Bit Mask . Type of 
Software 
SV_TYPE_WORKSTATION 1 0x00000001 Requester. 
SV_TYPE SERVER 2 0x00000002 Server. 
SV_TYPE_DOMAIN_CTRL 4 0x00000008 Domain 
controller. 
SV_TYPE_DOMAIN_BAKCTRL 5 0x00000010 Backup 
domain 
controller. 
SV_TYPE_TIME SOURCE 6 0x00000020 Time server. 
SV_TYPE_ALL All OxFFFFFFFF All types of 
servers. 


Only user and group information is replicated to the backup domain controller. 
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¢ svl_comment, which can be NULL, points to an ASCIIZ string containing a 
comment describing the server. 


Server Information (Level 2) 


struct server_info 2 { 


char 

unsigned 
unsigned 
unsigned 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char 

unsigned 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char far 


}3 


where: 


char 
char 
long 
* 


long 
long 
long 
short 
short 
* 
short 
short 
short 
short 
short 
short 
short 


char 
* 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 


short 
* 


sv2_name[CNLEN+1] ; 
sv2_version_major; 
sv2_version_minors; 
sv2_type; 
sv2_comment; 
sv2_ulist_mtime; 
sv2_glist_mtime; 
sv2_alist_mtime; 
sv2_users; 
sv2_disc; 
sv2_alerts; 
sv2_security; 
sv2_auditing; 
sv2_numadmin; 
sv2_lanmask; 
sv2_hidden; 
sv2_announce; 
sv2_anndelta; 
sv2_guestacct[UNLEN + 1]; 
sv2_padl; 
sv2_userpath; 
sv2_chdevs; 
sv2_chdevq; 
sv2_chdevjobs; 
sv2_connections; 
sv2_shares; 
sv2_openfiles; 
sv2_sessopens; 
SV2_SESSVCS; 
sv2_sessreqs; 
sv2_opensearch; 
sv2_activelocks; 
sv2_numreqbuf ; 
sv2_sizreqbuf; 
sv2_numbigbuf; 
sv2_numfiletasks; 
sv2_alertsched; 
sv2_erroralert; 
sv2_logonalert; 
sv2_accessalert; 
sv2_diskalert; 
sv2_netioalert; 
sv2_maxauditsz; 
sv2_srvheuristics; 


¢ sv2_name is an ASCIIZ string containing the name of a server. 


° sv2_version_major is the major release version number of the OS/2 LAN 
Requester/Server software. 
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¢ sv2_version_minor is the minor release version number of the OS/2 LAN 


Requester/Server software. 


¢ sv2_type indicates the type of software the computer is running, defined in 


SERVER.H as follows: 


Manifest Bit Mask Type of 
Software 
SV_TYPE_WORKSTATION 1 0x00000001 Requester. 
SV_TYPE_SERVER 2 0x00000002 Server. 
SV_TYPE_ DOMAIN CTRL 4 0x00000008 Domain 
controller. 
SV_TYPE_ DOMAIN BAKCTRL 5 0x00000010 Backup 
domain 
controller. 
SV_TYPE_TIME SOURCE 6 0x00000020 Time server. 
SV_TYPE_ALL All OxFFFFFFFF All types of 


servers. 


¢ sv2_comment, which can be NULL, points to an ASCIIZ string containing a 


comment describing the server. 


¢ sv2_ulist_mtime indicates the last time (in seconds from January 1,1970) the users 


list was modified. 


¢ sv2_glist_mtime indicates the last time (in seconds from January 1, 1970) the 


groups list was modified. 


¢ sv2_alist_mtime indicates the last time (in seconds from January 1, 1970) the 


access control list was modified. 


¢ sv2_users indicates the number of users that are allowed on the server. 


¢ sv2_disc indicates the auto-disconnect time (in minutes). A session is 
disconnected if it is idle longer than the time specified by sv2_disc. If sv2_disc is 


-1, auto-disconnect is not enabled. 


¢ sv2_alerts points to an ASCIIZ string containing the list of user names on the 
alert table of the server. Spaces separate the names. 


¢ sv2_security specifies the security type of the server. It is set to 
SV_USERSECURITY which is defined in SERVER.H. 


sv2_auditing indicates whether auditing is enabled on the server. If 0, auditing is 
disabled. If non-zero, the server is auditing all OS/2 LAN Requester/Server 
activities, as described in “Auditing Category” on page 3-43. 


sv2_numadmin indicates the number of administrators a server can accommodate. 


sv2_lanmask determines the order in which the network device drivers are served. 
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sv2_hidden determines whether the server is visible to other computers in the 
same domain. sv2_hidden is defined in in SERVER.H as follows: 


Manifest Value Meaning 
SV_VISIBLE 0 Server. 
SV_HIDDEN 1 Hidden server, not visible. 


sv2_announce specifies the network announce rate (in seconds), which determines 
how often the server will be announced to other computers on the network. 


sv2_anndelta specifies the random announce rate (in milliseconds) for 
sv2_announce. The announce interval (sv2_announce) can vary by the amount 
specified in sv2_anndelta (for example, it could vary from 9.99 seconds to 10.01 
seconds instead of being exactly 10 seconds each time). 


sv2_guestacct is an ASCIIZ string containing the name of a server’s reserved 
GUEST user account. 


sv2_padl WORD.-aligns the data structure components. 


sv2_userpath points to an ASCIIZ string containing the path name to user 
directories. 


sv2_chdevs indicates the number of serial devices that can be shared on the 
server. 


sv2_chdevg indicates the number of serial device queues that can coexist on the 
server. 


sv2_chdevjobs indicates the number of serial device jobs that can be pending on a 
server. 


sv2_connections indicates the number of connections to netnames that are 
allowed on a server. 


sv2_shares indicates the number of netnames a server can accommodate. 
sv2_openfiles indicates the number of files that can be opened at once. 
sv2_sessopens indicates the number of files that can be opened in one session. 
sv2_sessvcs indicates the maximum number of virtual circuits per client. 


sv2_sessreqs indicates the number of simultaneous requests that a client can 
make on any virtual circuit. 


sv2_opensearch indicates the number of searches that can be opened at once. 
sv2_activelocks indicates the number of file locks that can be active. 
sv2_numreqbuf indicates the number of server buffers that are provided. 
sv2_sizreqbuf indicates the size (in bytes) of each server buffer. 

sv2_numbigbuf indicates the number of 64KB server buffers that are provided. 


sv2_numfiletasks indicates the number of processes that can access the operating 
system at one time. 


sv2_alertsched indicates the alert interval (in seconds) for notifying an 
administrator of a network event. 
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¢ sv2_erroralert indicates the number of entries that can be written to the error log 
file during a sv2_alertsched interval before notifying an administrator. 


e sv2_logonalert indicates the number of invalid logon attempts to allow a user 
before notifying an administrator. 


¢ syv2_accessalert indicates the number of invalid file accesses to allow before 
issuing an administrative alert. 


¢ sv2_diskalert indicates the point at which (the number of kilobytes of free disk 
space) an administrator must be notified that the free space of a disk is low. 


¢ sv2_netioalert indicates the network I/O error ratio (in tenths of a percent) to 
allow before notifying an administrator. 


© sv2_maxauditsz indicates the maximum audit file size (in kilobytes). 


¢ sv2_srvheuristics points to an ASCIIZ string of flags used to control the 
operations of a server. 


The heuristics default to values that are optimal for most configurations and 
normally need not be changed. The default value for sv2_srvheuristics is defined 
in IBMLAN.INI as follows: 


srvheuristics=11110141111111011 
The maximum value for sv2_srvheuristics is defined in IBMLAN.INI as follows: 
srvheuristics = 12111191119119191 


If a partial string is specified, the default values are used for the remaining 
heuristics. If the string is NULL, or is not present in the IBMLAN.INI file, the 
default string is used. 


The result of using values other than those listed is undefined. 


The characters in the string (from left to right) have the following meaning. 
Unless otherwise defined, 0 turns off a heuristics feature, and 1 turns on the 
feature. 

The parameters and their descriptions are as follows: 


Parameter Description 


srvannounce Specifies the rate, in seconds, at which the server announces 
its presence on the network. 


Default value: 60 
Minimum value: 0 
Maximum value: 65535 


srvheuristics Sets a variety of server fine-tuning options. Each digit has 
an independent meaning. Missing digits are assumed to be 
the defaults as described. Except where noted, each is a 
binary digit where 0 means off or inactive, while 1 means on 
or active. The following are the meanings of the digits: 
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Digit Meaning 


0 


Use opportunistic locking when opening files. This 
lets the Server service assume that the first requester 
of the file is the only active process using that file. 
The server service will buffer the file and prevent a 
second requester from accessing the file until the 
buffer data is flushed. The default is 1. 


For opportunistic locking to occur, both this 
heuristic and wrkheuristic 0 in the requester must be 
active. 


Use read-ahead (read additional data to try to guess 
what the requester may want) when the requester is 
performing sequential access, as follows: 


Value Meaning 


0 Do not use read-ahead 
1 Use single-thread read-ahead 
2 Use asynchronous read-ahead thread. 


The default is 1. 


This heuristic pertains to reading ahead to the 
server's buffers (big buffers and requester buffers) 
from the file system and cache. 


Use write-behind (tell the requester a write is 
completed before actually performing the write). If 
the write generates an error, the error appears on a 
subsequent write. Files opened for write-through will 
not use write-behind. The default is 1. 


This heuristic pertains to writing behind from the 
server's buffers (big buffers and requester buffers) to 
the file system and cache. 


Use chain sends. The default is 1. 


For the chain send NETBIOS command to work, 
both this heuristic and wrkheuristic 8 in the requester 
must be active (set to 2, default). 


Check all incoming server message blocks (SMBs) for 
correct format. This is useful with mixed versions 
and brands of network software on the LAN. The 
default is 0. 


To prevent wasted CPU cycles in an OS/2 LAN 
Server environment, leave this heuristic at the 
default. 


Support file control block (FCB) opens (collapse all 
FCB opens for a file to a single open). This-is only 
useful for DOS applications on the network. The 
default is 0. 


Set the priority for the server. Lists the possible 
priority values (0 is the highest priority and 9 is the 
lowest). 
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Table 3-1. Server Priority 


Class of 
Priority Priority Level of Class 





The default is 4. 


Server priority is set to allow other applications to 
have CPU access also, if required. 


Automatically allocate more memory for searches if 
it runs out, up to 2048 searches. If DOS requesters 
are on the network, set this to 1. The default is 1. 


This heuristic pertains to directory searches 
(DosFindFirst). Memory is allocated dynamically 
instead of being locked up when it may not be 
needed. 


Write records to the audit trail only when the 
scavenger wakes up. The scavenger is a high-priority 
server thread that monitors the network for errors, 
writes to the error log and audit trail, and sends 
alerts 


When this is set to 0, any write to the audit trail 
wakes the scavenger. Heuristic 10 controls the 
wake-up interval of the scavenger. The default is 1. 


Do full buffering (as controlled by srvheuristics | and 
2) when a file is opened with deny-write sharing 
mode. When this is set to 0, deny write access has 
no buffering for any requester using this server. The 
default is 1. 


If an application breaks using buffering of deny-write 
opened files, use this heuristic to disable buffering for 
all requesters. 


Set the interval for the scavenger to wake up. The 
scavenger is a thread of the server process that 
performs the following tasks: 


e Automatic disconnection of sessions 


11 


12 


¢ Sending administrative alerts 
e Writing to the audit trail file. 
Set this entry as follows: 


Value Meaning 

5 seconds 
10 seconds 
15 seconds 
20 seconds 
25 seconds 
30 seconds 
35 seconds 
40 seconds 
45 seconds 
50 seconds. 


OMANADNRWN — © 


The default is 1. Heuristic 8 can cause the scavenger 
to wake up at other times. 


Allow compatibility-mode opens of certain types of 
files by translating them to sharing mode opens with 
deny-write. This is useful for sharing executable and 
other types of files. The default is 2. 


This heuristic controls how strictly the server 
enforces compatibility opens for read only. In the 
strictest sense of compatibility opening, if there is 
any open of a file with a sharing mode set, or if 
another session has the file open in compatibility 
mode, a compatibility-mode open of that file fails. 


The settings of this heuristic relax the strictness. The 
first level allows different Dos Requester machines to 
execute the same programs. The second level extends 
to batch files. The highest level translates 
compatibility-mode opens into a deny-none sharing 
mode open for read/write. Not all applications 
support this mode of operation. 


Values for srvheuristic 11 include the following: 


Value Meaning 


0 Do not use soft-compatibility opens. 

1 Use a deny-none sharing mode on .EXE and 
.COM files. 

2, Use a deny-none sharing mode on .EXE, 
.COM, .IMG and .BAT files. 

3 Use a deny-none sharing mode on all 


compatibility-mode opens. 
The default is 2. 


Allow Dos Requester machines to use a second 
virtual circuit when doing printer requests. If this is 
not set, a second virtual circuit ends any previous 
sessions set up for that Dos Requester machine. The 
default is 1. 
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Set the number of 64KB buffers used for read-ahead. 
Possible values are 0 to 9, where 0 means read-ahead 
is disabled. If this is set to a value larger than 
numbigbuf, then it is reset to the value of 
numbigbuf—1. 


Each 64K B buffer is divided into sixteen 4K B 
read-ahead buffers. You might want more than one 
big buffer allocated here if you are processing many 
files simultaneously with small reads. The default is 
1. 


Using 64KB (big buffers) for read-ahead involves a 
tradeoff between large file transfers and small-record 
read and write operations. Provided there are two 
64KB buffers remaining in the server for each 
requester doing concurrent large file transfers, you 
can use the remaining 64K B buffers for read-ahead 
without a penalty. 


Convert incoming path specifications into the most 
basic format that the OS/2 LAN Server understands. 
This conversion includes changing lowercase 
characters to uppercase, and slashes (used in path 
names) to backslashes (/ to \). The default is 0. 


Set the time the server waits before breaking an 
opportunistic lock. You may want to set a longer 
time when the network is subject to long delays. 
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Table 3-2 shows possible values: 


Table 3-2. Opportunistic Lock Timeout 
Time econ) 









Cs 
Ce 
ee 
ec 
ee 


The default is 0. 


If a second requester requests opening of a locked 
file, the server notifies the first requester to flush 
buffers and prepare for unlocking. If the first 
requester does not respond within the time specified 
here, the server closes the first requester’s open of the 
file. 


The server can lock a file opened in deny-none 
sharing mode (as long as there are no other requests 
to access the file) so that buffering can be used to 
enhance performance. The server provides exclusive 
use of the file to the first requester, preventing the 
second requester from accessing the file until buffer 
data is flushed (written to disk). This heuristic 
defines when the server breaks the lock and grants 
access to the second requester. 


Validate the input/output controls (IOCTLs) across 
the network. When this is set to 1 (on), the server 
accepts only generic device IOCTLs (categories 01H, 
05H, and OBH). See JBM OS/2 Programming Tools 
and Information for more information. 


With this heuristic set to 0 (off), the server could 
receive invalid IOCTL pointers because of differences 
in device drivers between vendors. This can shut 
down the server. You may need to set this heuristic 
to 0 to use certain device drivers, such as 
custom-built drivers. 


The default is 1. 
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17 Determines how long the server maintains unused 
dynamic big (64K B) buffers before freeing the 
memory. This digit can range from 0 through 9, 
with the following meanings: 


Digit Timeout 

0 seconds (immediately after use) 
1 second 

10 seconds 

1 minute 

5 minutes 

10 minutes 

20 minutes 

40 minutes 

1 hour 

Maintain big buffers indefinitely. 


OONNNAHRWN — © 


Default value: 1 (1 second). 


18 Determines how long the server waits after failing to 
allocate a big (64K B) buffer before trying again. 
This digit can be from 0 to 5, with the following 
meanings: 


Digit Timeout 


0 0 seconds (immediately after use) 

1 1 second 

2 10 seconds 

3 1 minute 

4 5 minutes 

5 10 minutes. 

Default value: 3 (1 minute). 

srvnets Lists names of the networks the server is to run on. Names 

of available networks are listed in the Networks section of 
the IBMLAN.INTI file. 


Required value: net! 


Srvpipes Sets the maximum number of pipes that the server uses. 
Increase this number if many users log on simultaneously. 


Default value: 3 
Minimum value: 1 
Maximum value: 20 


srvservices Specifies network services to start with the server service. 
This value is defined by the user at installation. 
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Server Information (Level 3) 


struct server_info_3 { 


char 

unsigned 
unsigned 
unsigned 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char 

unsigned 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
char far 
unsigned 


bs 


where: 


char 
char 
long 
* 


long 
long 
long 
short 
short 
* 
short 
short 
short 
short 
short 
short 
short 


char 
* 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
* 


short 


sv3_name[CNLEN+1] ; 
sv3_version_major; 
sv3_version_minor; 
sv3_type; 
sv3_comment ; 
sv3_ulist_mtime; 
sv3_glist_mtime; 
sv3_alist_mtime; 
sv3_users; 
sv3_disc; 
sv3_alerts; 
sv3_security; 
sv3_auditing; 
sv3_numadmin; 
sv3_lanmask; 
sv3_hidden; 
sv3_announce; 
sv3_anndelta; 
sv3_guestacct[(UNLEN + 1]; 
sv3_pad1; 
sv3_userpath; 
sv3_chdevs; 
sv3_chdevq; 
sv3_chdevjobs; 
sv3_connections; 
sv3_shares; 
sv3_openfiles; 
sv3_sessopens; 
Sv3_SeSSVCS3 
sv3_sessreqs; 
sv3_opensearch; 
sv3_activelocks; 
sv3_numreqbuf ; 
sv3_sizreqbuf; 
sv3_numbigbuf; 
sv3_numfiletasks; 
sv3_alertsched; 
sv3_erroralert; 
sv3_logonalert; 
sv3_accessalert; 
sv3_diskalert; 
sv3_netioalert; 
sv3_maxauditsz; 
sv3_srvheuristics; 
sv3_auditedevents; 


¢ sv3_name is an ASCIIZ string containing the name of a server. 


¢ sv3_version_major is the major release version number of the OS/2 LAN 
Requester/Server software. 


¢ sv3_version_minor is the minor release version number of the OS/2 LAN 
Requester/Server software. 
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¢ sv3_type indicates the type of software the computer is running, defined in 


SERVER.H as follows: 


Manifest Bit Mask Type of 
Software 
SV_TYPE_WORKSTATION 1 0x00000001 Requester. 
SV_TYPE_ SERVER 2 0x00000002 Server. 
SV_TYPE_ DOMAIN CTRL 4 0x00000008 Domain 
controller. 
SV_TYPE DOMAIN _BAKCTRL 5 0x00000010 Backup 
domain 
controller. 
SV_TYPE_TIME_ SOURCE 6 0x00000020 Time server. 
SV_TYPE ALL All OxFFFFFFFF  AIl types of 


servers. 


sv3_comment, which can be NULL, points to an ASCIIZ string containing a 
comment describing the server. 


sv3_ulist_mtime indicates the last time (in seconds from January 1, 1970) the 
users list was modified. 


sv3_glist_mtime indicates the last time (in seconds from January 1, 1970) the 
groups list was modified. 


sv3_alist_mtime indicates the last time (in seconds from January 1, 1970) the 
access control list was modified. 


sv3_users indicates the number of users allowed on the server. 


sv3_disc indicates the auto-disconnect time (in minutes). A session is 
disconnected if it is idle longer than the time specified by sv3_disc. If sv3_disc is 
-1, auto-disconnect is not enabled. 


sv3_alerts points to an ASCIIZ string containing the list of user names on the 
alert table of the server. Spaces separate the names. 


sv3_security specifies the security type of the server; the value is set to 
SV_USERSECURITY. 


sv3_auditing indicates whether auditing is enabled on the server. If 0, auditing is 
disabled. If non-zero, the server is auditing all OS/2 LAN Requester/Server 
activities, as described in “Auditing Category” on page 3-43. 


sv3_numadmin indicates the number of administrators that a server can 
accommodate. 


sv3_lanmask determines the order in which the network device drivers are served. 
sv3_hidden is set to SV_VISIBLE which is defined in SERVER.H. 


sv3_announce specifies the network announce rate (in seconds), which determines 
how often the server will be announced to other computers on the network. 


sv3_anndelta specifies the random announce rate (in milliseconds) for 
sv3_announce. The announce interval (sv3_announce) can vary by the amount 
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specified in sv3_anndelta (for example, it could vary from 9.99 seconds to 10.01 
seconds instead of being exactly 10 seconds each time). 


sv3_guestacct is an ASCIIZ string containing the name of the reserved GUEST 
user account of a server. 


sv3_pad1 WORD.-aligns the data structure components. 


sv3_userpath points to an ASCIIZ string containing the path name to user 
directories. 


sv3_chdevs indicates the number of serial devices that can be shared on the 
server. 


sv3_chdevgq indicates the number of serial device queues that can coexist on the 
server. 


sv3_chdevjobs indicates the number of serial device jobs that can be pending on 
the server. 


sv3_connections indicates the number of connections to netnames that are 
allowed on a server. 


sv3_shares indicates the number of netnames that a server can accommodate. 
sv3_openfiles indicates the number of files that can be open at once. 
sv3_sessopens indicates the number of files that can be open in one session. 
sv3_sessvcs indicates the maximum number of virtual circuits per client. 


sv3_sessregs indicates the number of simultaneous requests that a client can 
make on any virtual circuit. 


sv3_opensearch indicates the number of searches that can be opened at once. 
sv3_activelocks indicates the number of file locks that can be active. 
sv3_numreqbuf indicates the number of server buffers provided. 
sv3_sizreqbuf indicates the size (in bytes) of each server buffer. 
sv3_numbigbuf indicates the number of 64KB server buffers provided. 


sv3_numfiletasks indicates the number of processes that can access the operating 
system at one time. 


sv3_alertsched indicates the alert interval (in seconds) for notifying an 
administrator of a network event. 


sv3_erroralert indicates the number of entries that can be written to the error log 
file during a sv3_alertsched interval before notifying an administrator. 


sv3_logonalert indicates the number of invalid logon attempts to allow a user 
before notifying an administrator. 


sv3_accessalert indicates the number of invalid file accesses to allow before 
issuing an administrative alert. 


sv3_diskalert indicates the point (number of kilobytes of free disk space) at 
which an administrator must be notified that the free space of a disk is low. 


sv3_netioalert indicates the network I/O error ratio (in tenths of a percent) to 
allow before notifying an administrator. 


sv3_maxauditsz indicates the maximum audit file size (in kilobytes). 
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¢ sv3_srvheuristics points to an ASCIIZ string of flags used to control the 
operations of a server. See the heuristics information under “Server Information 


(Level 2).” 


¢ sv3_auditedevents is the audit event control mask as follows: 


Manifest 

SVAUD_SERVICE 
SVAUD_GOODSESSLOGON 
SVAUD_BADSESSLOGON 
SVAUD_SESSLOGON 
SVAUD_GOODNETLOGON 
SVAUD_BADNETLOGON 
SVAUD_NETLOGON 
SVAUD_LOGON 


SVAUD_GOODUSE 
SVAUD_BADUSE 
SVAUD_USE 


SVAUD_USERLIST 


SVAUD_PERMISSIONS 


SVAUD_RESOURCE 


SVAUD_LOGONLIM 


Meaning 

Service state change. 

Successful session logon requests. 
Unsuccessful session logon requests. 
All session logon and logoff requests. 
Successful network logon requests. 
Unsuccessful network logon requests. 
All network logon and logoff requests. 


All logon and logoff requests (network 
and session). 


Successful share requests. 
Unsuccessful share requests. 


All share requests, regardless of gooduse 
or baduse switches. 


Changes to the user or group account 
database. 


Changes to the access control list 
database. 


Resource access as defined by the 
per-resource auditing options specified 
in the access control list. 


Logon limit violations. 


Level 3 is not valid for the NetServerEnum2? call. 


The new field sv3_auditedevents is settable. 


For details on sv3_auditedevents, see ae_type, audit type, in “Auditing Category” on 


page 3-43. 
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Related Information 
For information on: 


¢ Domains—See the IBM Operating System/2 Local Area Network Server Version 
1.2 Network Administrator's Guide. 


¢ Remote administration of Net commands—See the IBM Operating System/2 
Local Area Network Server Version 1.2 Network Administrator's Guide. 


¢ Server heuristics—See the IBM Operating System/2 Local Area Network Server 
Version 1.2 Network Administrator's Guide. 
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NetServerAdminCommand 
The NetServerAdminCommand (admin, server, DOS) function executes a command 
on a server. 


Syntax 


#include <netcons.h> 
#include <server.h> 


unsigned far pascal 
NetServerAdminCommand(servername, command, result, buf, buflen, 
bytesread, totalavail) 


char far * servername; 
char far * command; 
short far * results 
char far * buf; 
unsigned short buflen; 


unsigned short far * bytesread; 
unsigned short far * totalavail; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


© command points to an ASCIIZ string containing the command to execute. 
¢ result points to the returned exit code of the executed command. 

¢ buf points to the output of the returned command. 

¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ bytesread points to an unsigned short integer indicating the number of bytes of 
information that were returned to buf. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_NAME 123 There is an incorrect 


character or incorrectly 
formed file system 
name. 


ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR_FILENAME EXCED RANGE 


ERROR_MORE_DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_ NoRoom 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR _WkstaNotStarted 


NERR _BrowserNotStarted 


NERR InternalError 


NERR _BadTransactConfig 


NERR_InvalidAPI 


NERR_TmpFile 


Value 
206 


234 


2102 


2104 


2106 


2114 


2119 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2316 


Meaning 


The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The server is currently 
out of the requested 


_ resource. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


A failure occurred 
when opening a remote 
temporary file. 
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Manifest Value Meaning 
NERR_TooMuchData 2317 The data returned 


from a remote 
administration 
command has been 
truncated to 64KB. 


NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


NERR_CantType 2357 The type of input 


cannot be determined. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCth(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosSemClear 


redir.GetNetInitPath. 


The NetServerAdminCommand function is a remote form of the C language library 
system() function. 


When executed remotely, NetServerAdminCommand sets the environment of the 
server as follows: 


The default drive and directory is c:\IBMLAN\NETPROG 
The PATH environment is not set (NULL). 


If executed locally, NetServerAdminCommand sets the environment of the server as 
follows: 


Related Information 


The current drive and directory of the caller are used 


The PATH environment is set to the user’s default path. 


For information on: 


Listing available servers—See “NetServerEnum2” on page 3-289. 


e Executing a program on a remote server—See “NetRemoteExec” on page 3-200. 
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NetServerDiskEnum 
The NetServerDiskEnum (admin, DOS) function retrieves a list of disk drives on a 
workstation. 


Syntax 
#include <netcons.h> 
#include <server.h> 


unsigned far pascal 
NetServerDiskEnum (servername, level, buf, 
buflen, entriesread, totalentries) 


char far * servername ; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
workstation. 


e level is a short integer that must be zero. 
¢ buf points to the returned list of disk drive names. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


° entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Return Codes 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 

ERROR_ACCESS DENIED 5 Administrative privilege is required. 

ERROR_INVALID_LEVEL 124 The Level parameter is invalid. 

ERROR_MORE DATA 234 Additional data is available, but the 
buffer is too small. 

NERR_NetNotStarted 2102 The redirector NETWKSTA.EXE 
has not been started. 

NERR ServerNotStarted 2114 The Server service has not been 
started. 

NERR_RemoteErr 2127 A remote API error has occurred. 

NERR _InternalError 2140 An internal error has occurred. 

NERR InvalidAPI 2142 The requested API is not supported 
on the remote server. 

NERR_InvalidComputer 2351 The specified computer name is 
invalid. 
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Remarks 
The NetServerDiskEnum function returns a list of local drive names for the specified 
workstation. The drive names in the list are consecutive strings, each containing a 
drive letter, a colon (:), and a NULL string terminator (\0). For example, the 
following can be returned for a server having two floppy drives (A: and B:), one 
hard drive (C:), and one RAM drive (E:): 


A:\0B:\OC:\0E:\0 


Related Information 
For information on: 
e Listing the shared resources of a server—See “NetServerEnum2” on page 3-289. 


e Listing available servers—See “NetServerEnum2” on page 3-289. 
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NetServerEnum2 


Syntax 


The NetServerEnum2 (DOS) function enumerates the set of all servers visible on the 
network. The type of NetServerEnum2 matches the bit mask in the field. 


#include <netcons.h> 
#include <server.h> 


unsigned far pascal 
NetServerEnum2(servername, level, buf, buflen, 


entriesread, totalentries, type, domain) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


unsigned long type 
char far * domain; 
where: 


servername points to an ASCIIZ string containing the name of a remote 
computer on which the function is to execute. A NULL pointer or string 
specifies a local computer. 


level is a short integer that specifies the level of detail (0 or 1) for the server_info 
data structure. 


Levels 2 and 3 are not valid for NetServerEnum2. 
buf points to the returned server_info data structure. 
buflen specifies the size (in bytes) of the buf memory area. 


entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


type is the bit mask of types to find; defined as follows: 


Manifest Bit Mask 
SV_TYPE_ WORKSTATION 0x00000001 
SV_TYPE_SERVER 0x00000002 
SV_TYPE_DOMAIN_CTRL 0x00000008 
SV_TYPE_ DOMAIN _BAKCTRL 0x00000010 
SV_TYPE_TIME SOURCE 0x00000020 
SV_TYPE_ALL OxFFFFFFFF 


domain points to the servers in this domain. 
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Return Codes 


Manifest 
NERR_ SUCCESS 


ERROR_NOT_ENOUGH_MEMORY 
ERROR_INVALID_ PARAMETER 
ERROR_INVALID_LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ServerNotStarted 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR _BrowserTableIncomplete 


NERR_NotLocalDomain 


NERR _InvalidComputer 
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Value 


87 


124 


234 


2102 


2114 


2134 


2138 


2139 


2140 


2141 


2319 


2320 


2351 


Meaning 


No errors were 
encountered. 


Sufficient memory is 
not available. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


The Server service has 
not been started. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The server table was 
initialized incorrectly. 


This domain is not 
active on this 
computer. 


The specified computer 
name is invalid. 


Remarks 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCthNETTRANSACTION) 
¢ DosFsCthhNULLTRANSACT) 


e DosSemClear. 


This function can obtain only level 0 and 1 data structures. The type parameter is 
tested (nondestructive bitwise AND) against the svx_type field of each entry. Only 
entries that match at least one of the specified bits are included in the entries 
returned in the buffer and in the counts placed in entriesread and totalentries. 


This API returns servers that are in the domain named in the domain argument. 
The named domain must be the domain of the requester, one of the oth_domains of 
the requester, or the Jogon_domains of the requester. If domain is NULL, the servers 
in all domains listed above are returned. If the domain is not one of the above 
values, the error NERR_NotLocalDomain is returned. If the domain argument is 
not NULL, entriesread and totalentries reflect the entries in the named domain. 


The restrictions on the value of domain apply to the computer on which the 
NetServerEnum2 API is actually executed, that is, the local computer if the 
servername argument is NULL, or the named server if the servername argument is 
not NULL. 
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NetServerGetinfo 
The NetServerGetInfo (partially admin, server, DOS) function retrieves information 
about a particular server. 


Syntax 


#include <netcons.h> 
#include <server.h> 


unsigned far pascal 
NetServergetinfo(servername, level, buf, buflen, totalavail) 


‘char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


e level specifies the level of detail (0, 1, 2, or 3) for the server_info data structure. 
e buf points to the returned server_info data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 
ERROR _INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR _ MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR _ ServerNotStarted 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OSZ2loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 


Value 
2104 


2106 


2114 


2123 


2127 


2134 


2138 


2139 


2140 


2141 


2351 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


e DosFreeSeg 


¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCth(NULLTRANSACT) 
¢ DosFsCti(NetGetRdrAddr) 


¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


¢ DosSemClear. 
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Remarks 
Depending on the level of information requested (by way of the /evel parameter), the 
NetServerGetInfo function returns information ranging from the name of the server 
to a description of the server heuristics, which control the manner in which the 
server operates. 


Level 0 and 1 information can be accessed remotely by ordinary users. 


Related information 
For information on: 


e Configuring a server—See “NetServerSetInfo” on page 3-295. 


¢ Server heuristics—See the JBM Operating System/2 Local Area Network Server 
Version 1.2 Network Administrator’s Guide. 


3-294 LAN Server Application Programmer’s Reference 


NetServerSetinfo 


Syntax 


The NetServerSetInfo (admin, server, DOS) function sets operating parameters for a 
server (individually or collectively). 


#include <netcons.h> 
#include <server.h> 


unsigned far pascal 
NetServerSetInfo(servername, level, buf, buflen, parmnum) 


char far * servername; 
short level; 

char far * buf; 
unsigned short buflen; 
short parmnum; 
where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


e level specifies the level of detail (1, 2 or 3) to be provided in the server_info data 
structure. 


¢ buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


e buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines whether buf contains a complete server_info data structure 
or a single data structure component. If parmnum is 0, buf must contain a 
server_info_1, server_info_2, or server_info_3 data structure. Otherwise, parmnum 
must specify the ordinal position value for one of the following data structure 
components, defined in SERVER.H as follows: 


Manifest Value Component 
SV_COMMENT_ PARMNUM 5 sv1_comment or 
sv2_comment 
SV_DISC_PARMNUM 10 sv2_disc 
SV_ALERTS_PARMNUM 11 sv2_alerts 
SV_HIDDEN PARMNUM 16 sv2_hidden 
SV_ANNOUNCE_PARMNUM 17 sv2_announce 
SV_ANNDELTA_PARMNUM 18 sv2_anndelta 
SV_ALERTSCHED PARMNUM 37 sv2_alertsched 
SV_ERRORALERT PARMNUM 38 sv2_erroralert 
SV_LOGONALERT_PARMNUM 39 sv2_logonalert 
SV_ACCESSALERT_PARMNUM 40 sv2_accessalert 
SV_DISKALERT_PARMNUM 41 sv2_diskalert 
SV_NETIOALERT_PARMNUM 42 sv2_netioalert 
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Return Codes 


Manifest 
SV_MAXAUDITSZ_PARMNUM 


Manifest 
NERR_SUCCESS 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_NOT_SUPPORTED 


ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR _ServerNotStarted 


NERR_NoRoom 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 
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50 


87 


124 


234 


2102 


2104 


2106 


2114 


2119 


2123 


2127 


2134 


2138 


2139 


Value Component 


sv2_maxauditsz 


Meaning 


No errors were 
encountered. 


Sufficient memory is 
not available. 


This request is not 
supported by the 
network. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The server is currently 
out of the requested 
resource. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


Ti requested 
information is not 
available. 


Manifest Value 


NERR_InternalError 2140 
NERR_BadTransactConfig 2141 
NERR_InvalidAPI 2142 
NERR_NetNameNotFound 2310 
NERR _InvalidComputer 2351 


Meaning 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


This shared resource 
does not exist. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Related Information 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_ NOT_FOUND] 


DosSemClear. 


For information on retrieving the configuration of a server, see “NetServerGetInfo” 
on page 3-292. 
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Service Category 
NetServiceControl (partially admin, DOS)—See “NetServiceControl” on page 3-310. 


NetServiceEnum (DOS)—See “NetServiceControl” on page 3-310. 
NetServiceGetInfo—See “NetServiceGetInfo” on page 3-317. 
NetServicelnstall (admin, DOS)—See “NetServicelInstall” on page 3-320. 
NetServiceStatus—See “NetServiceStatus” on page 3-323. 


The functions in the Service category start and control network service programs. 
All of these functions can be called on local machine with ordinary user’s privilege. 
For remote execution, administrative privilege is required except for the 
NetServiceEnum function. The functions in this category are used with the 
SERVICE.H and NETCONS.H include files. 


Description 
A service is a program of any size and function that other applications can use to 
perform some set of tasks on the network. An application starts and controls the 
operation of services with the functions in the Service category. 


The OS/2 LAN Requester/Server software provides ten standard services. The two 
most important of these are requester and server, which provide the majority of the 
software required to operate a local area network. When booting the OS/2 LAN 
Requester/Server software, the requester and server services are started first, then the 
services defined in the service section of the IBMLAN._INI file are started, followed 
by the server service. The netlogon service on the servers (primary domain controller, 
backup domain controller, or member of a domain) are started after the server 
service has been started. 


The following are descriptions of the tasks performed by the network services: 


Service Description 


alerter This service provides a system for notifying registered clients of 
certain classes of defined system events. 


The alerter service registers itself to receive all print, errorlog, and 
admin alerts, creating and registering a mailslot to receive alerts 
triggered by these events. When the a/erter service receives an 
alert, it converts the information to text and sends a message to 
all clients registered for that class of event by calling 
NetMessageBufferSend. (Print alerts regarding an individual 
print job are sent only to the user who submitted the print job.) 
For admin or errorlog alerts, the alerter service sends a message 
to all users listed in the sv2_alerts component of the server_info_2 
data structure. (A list of these users can be retrieved by calling 
the NetServerGetInfo function.) 


For more information on alert functions, see “Alert Category” 
on page 3-29. 
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Service Description 


requester This service is a primary one. It maintains most internal 
information and activates the network device drivers. If the 
requester service is paused, no redirection can be established to 
printers or serial devices. All currently redirected and opened 
devices can be used and closed, but not reopened, during a 
requester pause. If an application calls DosOpen while the 
requester service is paused, the function opens a local device of 
the specified name instead of the intended redirected device. 


The requester service cannot be removed while the server service 
is started. 


dlrinst This service downloads the DOS LAN Requester code from the 
server to the VOS LAN requesters. 


messenger This service enables the receiving and logging of messages sent 
among requesters by calling the Message category functions (see 
“Message Category” on page 3-157). The messenger service 
receives messages sent from remote computers by way of 
NetMessageBufferSend or NetMessageFileSend functions. For 
more details, see the JBM Operating System/2 Local Area 
Network Server Version 1.2 Network Administrator's Guide. 


netlogon This service provides logon verification. The server service must 
be started before netlogon can be started. 

netpopup This service displays messages on-screen. 

netrun This service supports the remote execution of processes. If the 


netrun service is paused, requests to remotely execute a program 
are denied. When the service is removed, each process that the 

service started is ended by the OS/2 DosKillProc function. The 
Server service must be started before the netrun service can be 


started. 

pcdosrpl This service enables the server service to support remote initial 
program load (remote IPL) of DOS requesters. 

replicator This service provides a file replication service. 

Server This service provides the basic functionality needed to share local 


resources over the network. If the server service is paused, all 
further requests for resources are denied. However, all current 
uses of shared resources continue. 


Time Hints for Starting and Stopping a Service 
For the services which take a long time to start or to stop, a mechanism is provided 
to feedback or “hint” to the process that started or stopped them. This mechanism 
allows the process to dynamically determine how long to wait for the service to 
complete the startup or stop, and in fact to provide the estimated time to the user, if 
determined by the application. The service can set the text field svci2_text as part of 
its status information. 


The services and programs that start or stop the services can use this mechanism to 
communicate during the start and stop operations. The control completion pending 
(CCP) code values are used when a service expects to take a long time to start or 
stop. Any service that has a nontrial initialization or shutdown task can use this 
method. 
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If a service is not using CCP codes, the code field should always be set to zero while 
the service status is INSTALL_PENDING or UNINSTALL_PENDING. 


The CCP codes divide the code field into fields as follows: 


33322222 222221111 111111 
21098765 432109876 54321098 76543210 


XXXXXXXX XXXXXXXXH TTTTTTTT CCCCCCCC 


X = not used (must be zero) 

H = hint is given SERVICE_CCP_QUERY_HINT 
T = time to wait SERVICE_CCP_WAIT_TIME 

C = check point number SERVICE_CCP_CHKPT_NUM 


Bits that are not used must be set to zero. 


Time to wait is the expected time to complete the current operation (start or stop), 
in tenths of a second. 


Check point number is a number that should be incremented, or at least changed to 
a higher value, each time the service calls NetServiceStatus. A service should call 
NetServiceStatus fairly often to keep updating this number, remembering that it is 
an 8-bit quantity. 


A controlling application that notes this check point value constantly changing will 
assume the service is still active. For that reason, the code that calls 
NetServiceStatus to update the CCP code should be in the main code path, and not 
in some time-triggered thread that might continue even while the current operation 
has halted due to an error. 


The “Hint” bit informs the application controlling the service that the other (time 
and count) information is valid. If this bit is set, the field svc2_text can contain an 
ASCIIZ string that, when displayed to a user, provides some information about the 
current state of the service. The service can continue to use a NULL string if it 
wishes to provide no text. It is up to the controlling application to make use of the 
text field, but it can assume that the text is suitable for display to the user. 


DOS Considerations 


Data Structures 


Under DOS, the functions are executed on a local requester. Attempting to execute 
the functions on a remote server returns ERROR_NOT_SUPPORTED. 


Under DOS, the services cannot be completely stopped; however, they can be paused 
and continued using NetServiceControl. 


The functions in the Service category use two types of data structures, one type 
containing basic status information, and the other containing different levels of 
detail. The NetServiceControl and NetServicelInstall functions use the service_info_2 
data structure. The NetServiceEnum and NetServiceGetInfo functions use the 
service_info data structures (level 0, 1 or 2). The NetServiceEnum returns 
information at three levels of detail (0 1, or 2); the /evel parameter controls the level 
of information returned. The NetServiceStatus function uses the service_status data 
structure. 
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Service Status 
The NetServiceStatus function uses the following data structure: 


struct service_status { 

unsigned short svcs_status; 

unsigned long svcs_code; 

unsigned short svcs_pid; 

char svcs_text [STXTLEN+1] ; 
bs 


where: 


¢ svcs_status specifies the status of the service. See svcil_status under Service 
Information (Level 1) for the possible values of this field. 


¢ svcs_code is the error code returned if the designated service stops or fails to 
start properly. 


¢ svces_pid is the program identification number (PID) of a service. 


¢ svcs_text isa NULL reserved ASCIIZ string, unless the service specified by 
svcs_pid is stopped. In this case, sves_text must specify a parameter string 
related to the svcs_code component. 


Service Information (Level 0) 


struct service_info_0 { 
char svci0_name[SNLEN+1]; 
+ 


where svci0_name is an ASCIIZ string containing the name of the network service to 
monitor. 
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Service Information (Level 1) 


struct service_info_1 { 

char svcil_name[SNLEN+1]; 
unsigned short svcil_status; 
unsigned long svcil_code; 
unsigned short svcil_pid; 


iz 
where: 


¢ svycil_name is an ASCIIZ string containing the name of the network service to 
monitor. 


¢ svcil_status is a bit map that indicates the status of the network service. The 
bits of svci/_status are defined as follows: 


Manifest/Bit Bit Meaning 
Mask 
SERVICE_INSTALL_STATE 0x03 The service is 


currently in one of 
the following start 


states: 
Start State Value Meaning 
SERVICE_UNINSTALLED 0x00 Service stopped. 
SERVICE_INSTALL_PENDING 0x01 Service start pending. 
SERVICE_UNINSTALL_PENDING 0x02 Service stop pending. 
SERVICE_INSTALLED 0x03 Service started. 
SERVICE_PAUSE_STATE 0x0C The service is 


currently in one of 
the following pause 


states: 
Pause State Value Meaning 
SERVICE_ACTIVE 0x00 Service active. 
SERVICE_CONTINUE_PENDING 0x04 Service continue 
pending. 
SERVICE_PAUSE_PENDING 0x08 Service pause 
pending. 
SERVICE PAUSED 0x0C Service paused. 
Bit 4 Indicates whether the 


service can be 
removed by an 
application, as 
indicated by one of 
the following bit 
settings: 


Bit Setting Value Meaning 
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Manifest/Bit 
SERVICE NOT_UNINSTALLABLE 
SERVICE_UNINSTALLABLE 


Bit 5 


Bit Setting 
SERVICE_PAUSABLE 


SERVICE_NOT_PAUSABLE 
Bit 6-7 


Bit 8-10 


Bit Setting 
SERVICE_REDIR_PAUSED 
SERVICE_REDIR_DISK_PAUSED 


SERVICE _REDIR_PRINT_PAUSED 


SERVICE _REDIR_COMM_PAUSED 


Bit 11-15 


Bit 
Mask 
0x00 


0x10 


Value 
0x20 


0x00 


Value 
0x700 
0x100 


0x200 


0x400 


Meaning 


Service cannot be 
removed. 


Service can be 
removed. 


Indicates whether the 
service can be paused 
by an application, as 
indicated by one of 
the following bit 
settings: 


Meaning 


Service can be 
paused. 


Service cannot be 
paused. 


Reserved, with a 
value of 0. 


Indicates whether 
particular tasks 
within the requester 
service have been 
paused, as indicated 
by one of the 
following bit settings: 


Meaning 
Redirector paused. 


Redirector for disks 
paused. 


Redirector for 
spooled devices 
paused. 


Redirector for serial 
devices paused. 


Reserved. 


svcil_code specifies an error code when a service stops or fails to start properly. 


For stopped services (SERVICE_UNINSTALL), the high word of svcil_code 
defines primary error codes and the low word of svcil_code defines secondary 
error codes. High-word values of svcil_code are defined as follows: 


Primary Error Code Value 


SERVICE_UIC_NORMAL 


Meaning 


Normal. 
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Primary Error Code Value Meaning 


SERVICE_UIC_BADPARMVAL 3051 Incorrect parameter value 
specified. 
SERVICE _UIC_MISSPARM 3052 Missing parameter. 
SERVICE_UIC_UNKPARM 3053 Unknown parameter 
specified. 
SERVICE_UIC_RESOURCE 3054 Insufficient resource. 
SERVICE_UIC_CONFIG 3055 Configuration faulty. 
SERVICE_UIC_SYSTEM 3056 OS/2 program error. 
SERVICE_UIC_INTERNAL 3057 Internal error encountered. 
SERVICE_UIC_AMBIGPARM 3058 Ambiguous parameter name. 
SERVICE_UIC_DUPPARM 3059 Parameter duplicated. 
SERVICE_UIC_KILL 3060 Ended by NetServiceControl 
when it did not respond. 
SERVICE_UIC_EXEC 3061 Could not execute service 
program file. 
SERVICE_UIC_SUBSERV 3062 Subservice failed to start. 
SERVICE_UIC_CONFLPARM 3063 Conflict in the value or use of 
these parameters. 
SERVICE _UIC_BADCOMPNAME 3064 Not a valid computer name. 


Low-word values of svcil_code are defined as follows: 


Secondary Error Code Value Meaning 
SERVICE_UIC_M_NULL 0 Normal. 
SERVICE_UIC_M_MEMORY 3070 Insufficient memory. 
SERVICE_UIC_M_DISK 3071 Insufficient disk space. 
SERVICE_UIC_M_THREADS 3072 Unable to create thread. 
SERVICE_UIC_M_PROCESSES 3073 Unable to create process. 
SERVICE_UIC_M_SECURITY 3074 Security failure. 
SERVICE_UIC_M_LANROOT 3075 Incorrect or missing default 
path. 
SERVICE_UIC_M_REDIR 3076 Network software not started. 
SERVICE _UIC_M_SERVER 3077 Server software not started. 
SERVICE_UIC_M_SEC_FILE_ERR 3078 Server could not access UAS 
database. 
SERVICE_UIC_M_FILES 3079 Not supported. 
SERVICE_UIC_M_LOGS 3080 Invalid IBMLAN\LOGS 
directory. 
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Secondary Error Code 


Value 
3081 


Meaning 


SERVICE_UIC_M_LANGROUP 


SERVICE_UIC_M_MSGNAME 


SERVICE_UIC_M_ANNOUNCE 


SERVICE_UIC_M_UAS 


3082 


3083 


3084 


Domain specified could not 
be used. 


Computer name being used as 
a message name on another 
computer. 


Requester failed to announce 
the server name. 


The UAS database is not 
configured correctly. 


For start or stop pending (SERVICE INSTALL_PENDING, 
SERVICE_UNINSTALL_PENDING) services, the bits of svcil_code are 


defined in SERVICE.H as follows: 


Start Pending Code 


SERVICE_CCP_NO_HINT 


SERVICE_CCP_CHKPT_NUM 


SERVICE_CCP_WAIT_TIME 


SERVICE_CCP_QUERY_HINT 


Bit Mask 


0x0 


OxFF 


0xFF00 


0x10000 


Meaning 


No reason given for 
start pending. 


Checkpoint number 
incremented each time 
the service calls the 
NetServiceStatus 
function (installer 
assumes incrementing 
denotes a valid service). 


Time to wait: expected 
time (tenths of a second) 
to start. 


Reason given for start 
pending. 


e svcil_pid is a program identification number (PID) for a service. 


Service Information (Level 2) 


struct service_info_2 { 


char 
unsigned short 


unsigned long svci2_code; 
unsigned short svci2_pid; 


char 


}s 


where: 


svci2_name[SNLEN+1] ; 
svci2_status; 


svci2_text [STXTLEN+1] ; 


svci2_name is an ASCIIZ string containing the name of the network service to 


monitor. 


svci2_status specifies the status of svci2_name. The bits of svci2_status are 


defined as follows: 
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Manifest/Bit 


SERVICE_INSTALL_STATE 


Start State 
SERVICE_UNINSTALLED 
SERVICE_INSTALL_PENDING 
SERVICE_UNINSTALL_PENDING 
SERVICE_INSTALLED 
SERVICE _PAUSE_STATE 


Pause State 
SERVICE_ACTIVE 
SERVICE_CONTINUE_PENDING 


SERVICE _PAUSE_PENDING 


SERVICE PAUSED 
4 


Bit Setting 
SERVICE_NOT_UNINSTALLABLE 


SERVICE_UNINSTALLABLE 


Bit Setting 
SERVICE_PAUSABLE 
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Bit 
Mask 
0x03 


Value 
0x00 
0x01 
0x02 
0x03 
0x0C 


Value 
0x00 
0x04 


0x08 


0x0C 


Value 
0x00 


0x10 


Value 
0x20 


Meaning 


The service is 
currently in one of 
the following start 
states: 


Meaning 

Service stopped. 
Service start pending. 
Service stop pending. 
Service started. 


The service is 
currently in one of 
the following pause 
states: 


Meaning 
Service active. 


Service continue 
pending. 


Service pause 
pending. 


Service paused. 


Indicates whether the 
service can be 
removed by an 
application, as 
indicated by one of 
the following bit 
settings: 


Meaning 


Service cannot be 
removed. 


Service can be 
removed. 


Indicates whether the 
service can be paused 
by an application, as 
indicated by one of 
the following bit 
settings: 


Meaning 


Service can be 
paused. 


Manifest/Bit 


SERVICE_NOT_PAUSABLE 


6-7 


8-10 


Bit Setting 
SERVICE_REDIR_ PAUSED 


SERVICE _REDIR_DISK_PAUSED 


SERVICE_REDIR_PRINT_PAUSED 


SERVICE_REDIR_COMM_PAUSED 


11-15 


Bit 
Mask 
0x00 


Value 
0x700 
0x100 


0x200 


0x400 


Meaning 


Service cannot be 
paused. 


Reserved, with a 
value of 0. 


Indicates whether 
particular tasks 
within the requester 
service have been 
paused, as indicated 
by one of the 
following bit settings: 


Meaning 
Redirector paused. 


Redirector for disks 
paused. 


Redirector for 
spooled devices 
paused. 


Redirector for serial 
devices paused. 


Reserved. 


¢ svci2_code specifies an error code when a service stops or fails to start properly. 
For stopped services (SERVICE_UNINSTALL), the high word of svci2_code 
defines primary error codes and the low word of svci2_code defines secondary 
error codes. The high word values of svci2_code are defined as follows: 


Primary Error Code 
SERVICE UIC_NORMAL 
SERVICE _UIC_BADPARMVAL 


SERVICE UVIC_MISSPARM 
SERVICE_UIC_UNKPARM 


SERVICE_UIC_AMBIGPARM 


SERVICE_UIC_DUPPARM 
SERVICE_UIC_RESOURCE 
SERVICE_UIC_CONFIG 
SERVICE_UIC_SYSTEM 
SERVICE_UIC_INTERNAL 


Value 


0 
3051 


3052 
3053 


3058 


3059 
3054 
3055 
3056 
3057 


Meaning 
Normal. 


Incorrect parameter value 
specified. 


Missing parameter. 


Unknown parameter 
specified 


Ambiguous parameter 
name. 


Duplicated parameter. 
Insufficient resource. 
Configuration faulty. 
OS/2 program error. 


Internal error encountered. 
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Primary Error Code 


SERVICE_UIC_KILL 


SERVICE_UIC_EXEC 


SERVICE_UIC_SUBSERV 
SERVICE_UIC_CONFLPARM 


SERVICE_UIC_BADCOMPNAME 


Value 


3060 


3061 


3062 
3063 


3064 


Meaning 


Ended by the 
NetServiceControl 
function. 


Could not execute service 
program file. 


Subservice did not start. 


Conflict in the value or use 
of these parameters. 


Not a valid computer 
name. 


The low-word values of svci2_code are defined as follows: 


‘Secondary Error Code 
SERVICE_UIC_M_NULL 
SERVICE_UIC_M_ MEMORY 
SERVICE_UIC_M_DISK 
SERVICE_UIC_M_THREADS 
SERVICE_UIC_M_PROCESSES 
SERVICE_UIC_M_SECURITY 
SERVICE_UIC_M_LANROOT 


SERVICE_UIC_M_REDIR 


SERVICE_UIC_M_SERVER 
SERVICE_UIC_M_SEC_FILE_ERR 


SERVICE_UIC_M_FILES 
SERVICE_UIC_M_LOGS 


SERVICE_UIC_M_LANGROUP 


SERVICE_UIC_M_MSGNAME 


SERVICE_UIC_M_ANNOUNCE 


SERVICE_UIC_M_UAS 
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Value 
0 
3070 
3071 
3072 
3073 
3074 
3075 


3076 


3077 
3078 


3079 
3080 


3081 


3082 


3083 


3084 


Meaning 

Normal. 

Insufficient memory. 
Insufficient disk space. 
Unable to create thread. 
Unable to create process. 
Security failure. 


Incorrect or missing default 
path. 


Network software not 
started. 


Server software not started. 


Server could not access 
UAS database. 


Not supported. 


Invalid IBMLAN\LOGS 
directory. 


Domain specified could not 
be used. 


Computer name being used 
as a message name on 
another computer. 


Requester did not 
announce the server name. 


The UAS database is not 
configured correctly. 


For start pending 
(SERVICE_INSTALL_PENDING/SERVICE_UNINSTALL_PENDING) 
services, the bits of svci2_code are defined in SERVICE.H as follows: 


Start Pending Code Bit Meaning 
Mask 
SERVICE_CCP_NO_HINT 0x0 No reason given for start 
pending. 
SERVICE_CCP_CHKPT_ NUM  0xFF Checkpoint number incremented 


each time the service calls the 
NetServiceStatus function 
(installer assumes incrementing 
denotes a valid service). 


SERVICE_CCP_WAIT_TIME OxFFOO Time to wait: expected time 
(tenths of a second) to start. 


SERVICE_CCP_QUERY_HINT 0x10000 Reason given for start or stop 
pending. 


¢ svci2_pid specifies the program identification number of a service. 


¢ svci2_text isa NULL reserved ASCIIZ string, except for stopped services 
(SERVICE _UNINSTALLED). In this case, svci2_text specifies a related 
parameter string for the svci2_code component. svci2_text cannot be longer than 
STXTLEN + 1 bytes in length. 
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NetServiceControl 


The NetServiceControl (admin, DOS) function controls the operations of network 


services. 
Syntax 


#include <netcons.h> 
#include <service.h> 


unsigned far pascal 

NetServiceControl(servername, service, opcode, 
arg, buf, buflen) 

char far * servername; 

char far * service; 

unsigned char opcode; 

unsigned char arg; 

char far * buf ; 

unsigned short buflen; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


computer. 


° service points to an ASCIIZ string containing the name of the network service 


being controlled. 


¢ opcode is a value indicating the action to perform on the service, defined in 


SERVICE.H as follows: 


Manifest/Bits Value 
SERVICE_CTRL_INTERROGATE 0 
SERVICE_CTRL_PAUSE 1 
SERVICE _CTRL_CONTINUE ps 
SERVICE_CTRL_UNINSTALL 3 
4-255 


Meaning 


Interrogate service 
status. 


Pause service. 
Continue service. 
Stop service. 


Reserved. 


¢ arg is a value that indicates the service-specific operation to perform. arg values 
for each service are defined in SERVICE.H. The requester pause and continue 


commands include the following options: 


Manifest Value 
SERVICE _CTRL_REDIR_DISK I 
SERVICE CTRL_REDIR_PRINT 2 
SERVICE CTRL_REDIR_COMM 4 


¢ buf points to the service_info_2 data structure. 


¢ buflen specifies the size (in bytes) of the buf memory area. 
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Meaning 
Disk resource. 
Print resource. 


Serial device. 


Return Codes 


Manifest 
NERR_ SUCCESS 


ERROR_ACCESS DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR _ INVALID _PARAMETER 


ERROR_INVALID_LEVEL 


NERR _NetNotStarted 


NERR _ ShareMem 


NERR_BufTooSmall 


NERR _ OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR ServiceTableLocked 


NERR ServiceNotInstalled 


NERR ServiceCtlTimeout 


Value 


124 


2102 


2104 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2180 


2184 


2186 
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Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The service does not 
respond to control 
actions. 


The service has not 
been started. 


The service is not 
responding to the 
control function. 
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Manifest Value Meaning 


NERR ServiceCtlBusy 2187 The service control is 
busy. 
NERR _ServiceNotCtrl 2189 The service cannot be 


controlled in its 
present state. 


NERR _ServiceKillProc 2190 The service was ended 
abnormally. 

NERR_ServiceCtlNotValid 2191 The requested pause or 
stop is not valid for 
this service. 

NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFlagProcess 
¢ DosFreeSeg 
* DosFsCtlhKNETTRANSACTION) 
¢ DosFsCtlh(NULLTRANSACT) 
¢ DosFsCti(NetGetRdrAddr) 
¢ DosGetInfoSeg 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear 
¢ DosSemWait. 
Remarks 
If the operation requested by the control opcode takes a long time to complete, the 
status and code values that NetServiceControl returns may be intermediate. Thus, 


for long-running operations, an application should issue successive calls to 
NetServiceControl to verify that the operation has completed. 


NetServiceControl acts only on services that are started. If a service is in the 
UNINSTALLED, UNINSTALL_PENDING, or INSTALL_PENDING state, 
NetServiceControl returns the NERR_ServiceCtlNotValid error code. There is one 
exception to this rule. An application can pass the opcode parameter with the value 
0 (interrogation) to query the last known state of a stopped service. (If a service has 
never been started, NetServiceControl returns the NERR_ServiceNotInstalled error 
code.) 


Services can be written to recognize a particular set of opcodes, as appropriate. 
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Related Information 
For information on: 


e Listing the services started on a server—See “NetServiceEnum” on page 3-314. 


¢ Updating status and code information for a service—See “NetServiceStatus” on 
page 3-323. 
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NetServiceEnum 


Syntax 


Return Codes 


The NetServiceEnum (DOS) function retrieves information about all network 
services that are started. 


#include <netcons.h> 
#include <service.h> 


unsigned far pascal 
NetServiceEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 

char far * buf; 

unsigned short buflen; 
unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


* servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ level specifies the level of detail (0, 1, or 2) requested for the service_info data 
structure. 


¢ buf points to the service_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR _INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 
available, but the 
buffer is too small. 
NERR_NetNotStarted 2101 The device driver is 


not started. 
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Manifest Value Meaning 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_OS2loctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _ InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR _InvalidAPI 2142 The requested API is 


not supported on the 
remote server. 


NERR_ServiceTableLocked 2180 The service does not 
respond to control 
actions. 

NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtl(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_ NOT_FOUND] 


DosSemClear. 


The NetServiceEnum function returns information only on services that are in the 
Start state. 


Chapter 3. API Function Descriptions 3-315 


Related Information 
For information on updating the status and code information for a network service, 
see “NetServiceStatus” on page 3-323. 
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NetServiceGetinfo 


Syntax 


Return Codes 


The NetServiceGetInfo function retrieves information about a particular network 
service that is started. 


#include <netcons.h> 
#include <service.h> 


unsigned far pascal 
NetServiceGetInfo (servername, service, level, 
buf, buflen, totalavail) 


const char far * servername; 
const char far * service; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


* servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ service points to an ASCIIZ string containing the name of the network service 
for which information is being requested. 


e level specifies the level of detail (0, 1, or 2) requested for the returned service_info 
data structure. 


¢ buf points to the service_info data structure. 
¢ buflen tells the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR INVALID PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_ LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2101 The device driver is 


not started. 


Chapter 3. API Function Descriptions 3-317 


Manifest Value Meaning 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_BufTooSmall 2123 The buffer is too small 


for fixed-length data. 


NERR_OS2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 
NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 
NERR_InternalError 2140 An internal error has 
occurred. 
NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 
NERR_InvalidAPI 2142 The requested API is 


not supported on the 
remote server. 


NERR _ServiceTableLocked 2180 The service does not 
respond to control 
actions. 

NERR ServiceNotInstalled 2184 The service has not 


been started. 


NERR_InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtlh(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 
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Remarks 
The NetServiceGetInfo function returns the NERR_ Success code for services that 
are not started (SERVICE_UNINSTALLED). If a service is stopped, an application 
can examine the available data of a server using NetServiceControl. 


NetServiceGetInfo function is similar to the NetServiceControl function passed with 
the INTERROGATE opcode. However, NetServiceGetInfo does not interrogate the 
service; it only retrieves the status that the service last posted. 


Related Information 


For information on controlling the operations of a network service, see 
“NetServiceControl” on page 3-310. 
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NetServiceinstall 


The NetServiceInstall (admin, DOS) function starts a network service. 


Syntax 


#include <netcons.h> 
#include <service.h> 


unsigned far pascal 


NetServiceInstall(servername, service, cmdargs, buf, buflen) 


char far * servername; 
char far * service; 
char far * cmdargs; 
char far * buf; 


unsigned short buflen; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


computer. 


¢ service points to an ASCIIZ string containing the name of the network service to 


Start. 


¢ cmdargs points to an ASCIIZ string containing the command parameters for 
service. cmdargs can be a NULL pointer or can point to a series of ASCIIZ 
string parameters ended by a NULL ending character in one of the following 


forms: 

param: value\0 >- ASCIIZ parameter 

param\0 >- ASCIIZ parameter 
param=value\0 >- ASCIIZ parameter 

\@ >- Null parameter ends list 


cmdargs parameters are merged with service component parameters from the 


IBMLAN.INI file and passed to the service program. 


¢ buf points to the service_info_2 data structure. 


e buflen specifies the size (in bytes) of the buf memory area. 


Return Codes 
Manifest 
NERR_SUCCESS 


ERROR PATH NOT_FOUND 
ERROR_ACCESS_ DENIED 


ERROR_NOT_ENOUGH_MEMORY 
ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 
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Value 
0 


87 


124 


Meaning 


No errors were 
encountered. 


The path was not found. 


Administrative privilege is 
required. 


Sufficient memory is not 
available. 


The specified parameter is 
invalid. 


The Level parameter is 
invalid. 


Manifest 
NERR_NetNotStarted 


NERR_ShareMem 
NERR_BufTooSmall 
NERR _LanIniError 
NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 
NERR_InvalidAPI 

NERR _LineTooLong 
NERR ServiceTableLocked 


NERR ServiceTableFull 
NERR Servicelnstalled 


NERR _ServiceEntryLocked 


NERR_BadServiceName 


NERR _ServiceCtiTimeout 


Value 
2102 


2104 


2123 


2131 


2134 


2138 


2139 


2140 


2141 


2142 


2149 


2180 


2181 
2182 


2183 


2185 


2186 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The buffer is too small 
for fixed-length data. 


An error occurred when 
opening. or reading the 
IBMLAN_INI file. 


An internal error 
occurred when calling the 
workstation driver. 


The Requester service has 
not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is not 
supported on the remote 
server. 


A line in the 
IBMLAN._INI file is too 
long. 


The service does not 
respond to control 
actions. 


The service table is full. 


The requested service has 
already been started. 


The service does not 
respond to control 
actions. 


The service name is 
invalid. 


The service is not 
responding to the control 
function. 
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Manifest Value 


NERR_ServiceCtlBusy 2187 
NERR_BadServiceProgName 2188 
NERR_InvalidComputer 2351 


Meaning 


The service control is 
busy. 


The IBMLAN.INI file 
contains an invalid 
service program name. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosAllocShrSeg-[ERROR_ALREADY_EXISTS] 
¢ DosChgFilePtr 

¢ DosExecPgm 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCthKNETTRANSACTION) 

¢ DosFsCtl(NULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosOpen[-ERROR_OPEN_FAILED] 

¢ DosRead 

¢ DosSemClear 

¢ DosSemWait-[ERROR_SEM_TIMEOUT] 


¢ DosStartSession. 


Remarks 


The name of the service is found in the IBMLAN.INI file. The executable file name 
of the service is matched to a corresponding entry in the SERVICES component of 
the IBMLAN.INI file. Any relative file path name supplied for service is assumed 
relative to the OS/2 LAN Requester/Server root directory (\IBMLAN\). 


Related Information 
For information on: 


¢ Controlling network services—See “NetServiceControl” on page 3-310. 


e Listing available servers—See “NetServerEnum2” on page 3-289. 
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NetServiceStatus 


Syntax 


Return Codes 


Remarks 


Related Information 


The NetServiceStatus function sets status and code information for a network 
service. 


#include <netcons.h> 
#include <service.h> 


unsigned far pascal 
NetServiceStatus (buf, buflen) 
const char far * buf; 
unsigned short buflen; 


where: 
¢ buf points to the service_status data structure. 


e buflen specifies the size (in bytes) of the buf memory area. 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were encountered. 

ERROR_ACCESS DENIED 5 Administrative privilege is required. 

NERR_NetNotStarted 2101 The device driver is not started. 

NERR_BufTooSmall 2123 The buffer is too small for 
fixed-length data. 

NERR_WkstaNotStarted 2138 The Requester service has not been 
started. 

NERR ServiceTableLocked 2180 The service does not respond to 


control actions. 


NERR ServiceNotInstalled 2184 The service has not been started. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosGetInfoSeg 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND]. 


Service applications must call NetServiceStatus to update their status and code tables 
each time their status changes. 
If a non-service application (one not started by a call to NetServiceInstall) calls 


NetServiceStatus, then NetService returns the NERR_ServiceNotInstalled error code. 


For information on controlling the operation of a network service, see 
“NetServiceControl” on page 3-310. 
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_ Session Category 


Description 


Data Structures 


NetSessionDel (admin, server, DOS)—See “NetSessionDel” on page 3-328. 


- NetSessionEnum (partially admin, server, DOS)—See “NetSessionEnum” on 


page 3-331. 


NetSessionGetInfo (partially admin, server, DOS)—See “NetSessionGetInfo” on 
page 3-334. 


The functions in the Sessions category control network sessions established between 
requesters and servers. They are used with the SHARES.H and NETCONS.H 
include files. 


A session is literally a path between a requester and a server. A requester begins a 
session with a server the first time it requests to connect to.a shared resource on the 
server. Any further connections from the requester to the other shared resources on 
the same server do not create another session; multiple connections can be serviced 
on one session. 


To end a session, an application calls the NetSessionDel function. This action 
deletes all current connections between the requester and the server. 


The NetSessionEnum function returns information about all sessions established 
with a server. 


To obtain information about a particular session, an application calls the 
NetSessionGetInfo function. 


The /evel parameter controls the level of information that the NetSessionEnum and 
NetSessionGetInfo functions return. 


Session Information (Level 0) 


struct session_info_0 { 
char far * sesi0_cname; 
}3 


where: 


¢ sesi0_cname points to an ASCIIZ string containing the computer name of the 
requester that established the session. 
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Session Information (Level 1) 


struct session_info_1 { 


iE 


char far * 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 


where: 


Session Information (Level 2) 


* 


short 
short 
short 
long 
Jong 
long 


sesil_cname; 
sesil_username; 
sesil_num_cons; 
sesil_num_opens; 


sesil_num_users; 
sesil_sess time; 
sesil_idie_time; 
sesil_user_flags; 


sesil_cname points to an ASCIIZ string containing the computer name of the 
requester that established the session. 


sesil_username points to an ASCIIZ string containing the name of the user who 
established the session. 


sesil_num_conns indicates the number of connections that have been made 
during the session. 


sesil_num_opens indicates the number of files, devices, and pipes that have Dern 
opened during the session. 


sesil_num_users specifies the number of sessions that are established between the 
server and the requester. 


sesil_sess_time indicates the number of seconds a session has been active. 


sesil_idle_time indicates the number of seconds a session has been idle. 


sesil_user_flags indicates the manner in which the user established the session. 
The bit mask for sesil_user_flags is defined in SHARES.H as follows: 


Manifest 


SESS_GUEST 


SESS_NOENCRYPTION 


struct session_info 2 { 


i 


char far 
char far 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 


* 
* 


short 
short 
short 
long 
long 
long 


char far * 


where: 


sesi2_cname; 

sesi2_username; 
sesi2_num_conns; 
sesi2_num_opens; 
sesi2_num_users; 
sesi2_sess time; 
sesi2_idle_ time; 


sesi2_user_flags; 
sesi2_cltype_name; 


Value 
l 
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Meaning 


sesil_username established the 
session using a GUEST account. 


sesil_username established the 
session without using password 
encryption. 
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° sesi2_cname points to an ASCIIZ string containing the computer name of the 
requester that established the session. 


© sesi2_username points to an ASCIIZ string containing the name of the user who 
established the session. 


¢ sesi2_num_conns indicates the number of connections that have been made 
during the session. 


© sesi2_num_opens indicates the number of files, devices, and pipes that have been 
opened during the session. 


¢ sesi2_num_users specifies the number of sessions that are established between the 
server and the requester. 


e sesi2_sess_time indicates the number of seconds a session has been active. 
© sesi2_idle_time indicates the number of seconds a session has been idle. 


© sesi2_user_flags indicates the manner in which the user established the session. 
The bit mask for sesi2_user_flags is defined in SHARES.H as follows: 


Manifest Value Meaning 

SESS_GUEST 1 sesi2_username established the 
session using a GUEST account 

SESS_NOENCRYPTION 2 sesi2_username established the 
session without using password 
encryption. 


¢ sesi2_cltype_name specifies the type of client that established the session. The 
defined types are as follows: 


Type Meaning 

Down Level Old clients; for example, PLCP 
DOS LM 1.0 DOS LAN Manager 1.0 clients 
DOS LM 2.0 DOS LAN Manager 2.0 clients 
OS/2 LS 1.0 OS/2 LAN Server 1.0 clients 
OS/2 LS 1.2 OS/2 LAN Server 1.2 clients 


Session Information (Level 10) 
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struct session_info_ 10 { 
char far * sesil0_cname; 
char far * sesil@_ username; 
unsigned long sesil@ sess time; 
unsigned long sesil@_idle_time; 
}s 


where: 


¢ sesil0_cname points to an ASCIIZ string containing the computer name of the 
requester that established the session. 


¢ sesil0_username points to an ASCIIZ string containing the name of the user who 
established the session. 
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¢ sesil0_sess_time indicates the number of seconds a session has been active. 


¢ sesil0_idle_time indicates the number of seconds a session has been idle. 
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NetSessionDel 
The NetSessionDel (admin, server, DOS) function ends a session between a requester 
and a server. 


Syntax 


#include <netcons.h> 
#include <shares.h> 


unsigned far pascal 

NetSessionDel (servername, workstation, reserved) 
char far * servername; 

char far * workstation; 

short reserved; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ workstation points to an ASCIIZ string containing the name of the requester 
that established the session being discontinued. 


e reserved must be 0. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 | Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR _ INVALID PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 


NETWKSTA.EXE has 
not been started. 


NERR_ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 


3-328 LAN Server Application Programmer’s Reference 


Manifest 
NERR ServerNotStarted 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR InvalidComputer 
NERR_NoSuchServer 


NERR_NoSuchSession 


Value 
2114 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2351 


2460 


2461 


Meaning 


The Server service has 
not been started. 


The buffer is too smail 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The specified computer 
name is invalid. 


The server ID is not 
valid. 


The session ID is not 
valid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


¢ DosFsCtlh(NETTRANSACTION) 
¢ DosFsCtlh(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 


e¢ DosGetProcAddr 


° DosGetShrSeg[-ERROR_FILE_NOT_ FOUND] 


¢ DosLoadModule 


¢ DosSemClear. 
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Remarks 
All connections established by way of the session are disconnected when the session 
is deleted, and any files that were opened by way of the session are closed. Data 
may be lost if any process on the requester is communicating with the server when 
NetSessionDel is called. 


Related Information 


For information on retrieving the status of the session of a server, see 
“NetSessionGetInfo” on page 3-334. 
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NetSessionEnum 
The NetSessionEnum (partially admin, server, DOS) function provides information 
on all current sessions to a server. Users with less than administrative privileges 
receive session information at level 0 or level 10. 


Syntax 


#include <netcons.h> 
#include <shares.h> 


unsigned far pascal 
NetSessionEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ level specifies the level of detail (0, 1, 2 or 10) requested for the returned 
session_info data structure. 


e buf points to the returned data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR _INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR _ INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_ServerNotStarted 


NERR_OS2loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 


Value 


234 


2102 


2104 


2106 


2114 


2134 


2138 


2139 


2140 


2141 


2351 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


DosFsCtl(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 
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Related Information 
For information on: 


e Deleting a session—See “NetSessionDel” on page 3-328. 


e Listing all sessions redirected to a resource—See “NetConnectionEnum” on 
page 3-78. 
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NetSessionGetinfo 
The NetSessionGetInfo (partially admin, server, DOS) function retrieves information 
about a session established between a particular requester and server. Users with 
less than administrative privileges receive session information at level 0 or level 10. 


Syntax 


#include <netcons.h> 
#include <shares.s> 


unsigned far pascal 
NetSessionGetInfo(servername, workstation, level, 
buf, buflen, totalavail) 


char far * servername ; 
char far * workstation; 
short level; 

char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ workstation points to an ASCIIZ string containing the name of the requester 
whose session is to be monitored. 


e level specifies the level of detail (0, 1, 2, or 10) requested for the returned 
session_info data structure. 


¢ buf points to the session_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR _INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 
NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_ClientNameNotFound 


NERR_InvalidComputer 


Value 
234 


2102 


2104 


2106 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


2312 


2351 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


A session does not 
exist with that 
computer name. 


The specified computer 
name is invalid. 
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Other error return codes may be returned from the following OS/2 functions: 


Related Information 


DosFsRamSemClear 

DosFreeSeg 

DosFsCthNETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


For information on listing all sessions redirected to a resource, see 
“NetConnectionEnum” on page 3-78. 
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Share Category 


Description 


NetShareAdd (admin, server, DOS)—See “NetShareAdd” on page 3-340. 
NetShareCheck (server, DOS)—See “NetShareCheck” on page 3-344. 

NetShareDel (admin, server, DOS)—See “NetShareDel” on page 3-347. 
NetShareEnum (partially admin, server, DOS)—See “NetShareEnum” on page 3-350. 


NetShareGetInfo (partially admin, server, DOS)—See “NetShareGetInfo” on 
page 3-353. 


NetShareSetInfo (admin, server, DOS)—See “NetShareSetInfo” on page 3-356. 


The functions in the Share category control shared resources.. They are used with 
the SHARES.H, ACCESS.H, and NETCONS.H include files. 


Share is the term applied to the local device of a server (such as a disk drive, print 
device, or named pipe) that other applications on the network can access. A unique 
netname is assigned to each shared resource to enable remote users and applications 
to refer to the share, rather than the local device name of the share. 


The first step for allowing remote users and applications to access a server resource 
is to share the resource, giving it a netname. This is done with the NetShareAdd 
function, which adds a share to a server. The function requires information about 
the resource type. 


On a server, NetShareAdd requires only a netname and a local device name to share 
a resource. A user or application must have an account on the server to access the 
resource. For information on setting up user accounts in the user accounts 
subsystem (UAS) database, see “User Category” on page 3-382. For information on 
assigning permissions, see “Access Permission Category” on page 3-2. 


DOS Considerations 


Data Structures 


Under DOS, the functions can be executed only on a remote server. Attempting to 
execute the functions on a local requester returns NERR_RemoteOnly. 


Share information can be returned by the NetShareEnum and NetShareGetInfo 
functions at one of three levels of detail specified by the level parameter (values 0, 1, 
or 2) NetShareAdd requires level 2 of detail. NetShareSetInfo can be called with 
level 1 or 2. NetShareCheck and NetShareDel do not use. or return data structures. 


The following data structures are associated with level values 0, 1, and 2. 


Share Information (Level 0) 


struct share_info_0 { 
char shi0_netname[NNLEN+1] ; 
}; 


where: 
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¢ shi0_netname is an ASCIIZ string containing the netname of a resource. 


Share Information (Level 1) 


struct share_info_l { 


char shil_netname[NNLEN+1]; 
char shil_padl; 
unsigned short shil_type; 
char far * shil_remark; 
}; 
where: 


¢ shil_netname is an ASCIIZ string containing the netname of a resource. 
¢ shil_pad] WORD-aligns the data structure components. 


e shil_type is one of four values indicating the type of share, as defined in 


SHARES.H: 

Manifest Value Share Type 
STYPE_DISKTREE 0 Disk drive. 
STYPE_PRINTQ 1 Spooler queue. 
STYPE_DEVICE Zz Serial device. 

STYPE_IPC 3 Interprocess communication 


(IPC). 


¢ shil_remark points to an ASCIIZ string containing an optional comment about 
the shared resource. 


Share Information (Level 2) 


struct share_info_2 { 


char shi2_netname[NNLEN+1] ; 
char shi2_pad1; 

unsigned short shi2_type; 

char far * shi2_remark; 


unsigned short shi2_permissions; 
unsigned short shi2_max_uses; 
unsigned short shi2_current_uses; 
char far * shi2_path; 


char shi2_passwd[SHPWLEN+1] ; 
char shi2_pad2; 

}; 

where: 


¢ shi2_netname is an ASCIIZ string containing the netname of a resource. 
¢ shi2_pad] WORD-aligns the data structure components. 


¢ shi2_type is one of four values indicating the type of share, as defined in 
SHARES.H as follows: 
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Manifest Value Meaning 


STYPE DISKTREE 0 Disk drive. 

STYPE_PRINTQ 1 Spooler queue. 

STYPE_DEVICE ps Serial device. 

STYPE_IPC 3 Interprocess communication 
(IPC). 


Note: The shi2_type value affects the requirements for certain other share_info_2 
components when the NetShareAdd function is called. See “Remarks” in the 
function reference section for details. 


¢ shi2_remark points to an ASCIIZ string containing an optional comment about 
the shared resource. 


¢ shi2_permissions is reserved. 


¢ shi2_max_uses gives the maximum number of concurrent connections that the 
shared resource can accommodate (unlimited if the shi2_max_uses value is -1). 


© shi2_current_uses indicates the number of connections that are currently made to 
the resource. 


¢ shi2_path points to an ASCIIZ string containing the local path name of the 
shared resource. For disks, shi2_path is the path being shared. For spooler 
queues, shi2_path is the name of the spooler queue being shared. For serial 
device queues, shi2_path is a string of one or more communication device names 
separated by spaces (for example, COM1 COM2 COM6). 


¢ shi2_passwd is a reserved field and it must be NULL. 
¢ shi2_pad2 WORD-aligns the data structure components. 


Related Information 
For information on: 


¢ User accounts—See “User Category” on page 3-382. 


e Access permissions—See “Access Permission Category” on page 3-2. 
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NetShareAdd 


The NetShareAdd (admin, server, DOS) function shares the resource of a server. 
Syntax 

#include <netcons.h> 

#include <shares.h> 


#include <access.h> 


unsigned far pascal 
NetShareAdd(servername, level, buf, buflen) 


char far * servername; 
short levels; 
char far * buf; 


unsigned short buflen; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
. on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ level specifies the level of detail (2) provided by the share_info_2 data structure. 
¢ buf points to the share_info_2 data structure. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_NAME 123 There is an incorrect 


character or incorrectly 
formed file system 


name. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 


ERROR_FILENAME_EXCED_RANGE 206 The file name is longer 
than 8 characters or 
the extension is longer 
than 3 characters. 
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Manifest 
NERR _NetNotStarted 


NERR_UnknownServer 


NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_UnknownDevDir 


NERR _ RedirectedPath 


NERR_DuplicateShare 


NERR_ NoRoom 


NERR_TooManyltems 


NERR_BufTooSmail 


NERR_OS82IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_QNotFound 


Value 
2102 


2103 


2104 


2106 


2114 


2116 


2117 


2118 


2119 


2121 


2123 


2134 


2138 


2139 


2140 


2141 


2150 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


The server cannot be 
located. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The device or directory 
does not exist. 


The operation is 
invalid on a redirected 
device. 


The name has already 
been shared. 


The server is currently 
out of the requested 
resource. 


The requested add of 
item exceeds maximum 
allowed. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The printer queue does 
not exist. 
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Manifest Value Meaning 


NERR_DeviceShareConflict 2318 This device cannot be 
shared as both a 
spooled and a 
non-spooled device. 


NERR_BadDevString 2340 This list of devices is 
invalid. 
NERR_BadDev 2341 The requested device is 
invalid. 
NERR_InUseBySpooler 2342 This device is already 
in use by the spooler. 
NERR_InvalidComputer 2351 The specified computer 
name is invalid. 
NERR_CantType 2357 The type of input 


cannot be determined. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosDevIOCtl 
¢ DosFsRamSemClear 
¢ DosFsRamSem Request 
¢ DosFreeSeg 
¢ DosFsCtl(NETTRANSACTION) 
¢ DosFsCtl(NIOCGETASGLIST) 
¢ DosFsCtlh(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetProcAddr 
¢ DosGetShrSeg 
¢ DosLoadModule 


¢ DosPrintDestGetInfo[-NERR_SpoolerNotLoaded, 
NERR_DestNotFound,ERROR_MORE DATA] 


¢ DosSemClear 

¢ DosSemRequest 

¢ redir.GetNetInitPath 

¢ redir.NIOCGETASGLIST1L 1. 
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Remarks 
Depending on the type of share specified by the value in the shi2_type component of 


the share_info_2 data structure, other components in the data structure must be 
specified as follows: 


Manifest Value Component Requirements 

STYPE_DISKTREE 0 shi2_path must specify a file system 
path name. 

STYPE_PRINTQ 1 shi2_netname must specify the name 


of an existing spooler queue. It is 
recommended that the netname and 
the path be the same; otherwise, the 
result is unpredictable. 


STYPE_ DEVICE 2 shi2_path must be passed as a 
NULL pointer or point to a list of 
print destinations, separated by 
spaces. The list must be the same as 
those specified for the spooler queue. 


STYPE_IPC 3 shi2_netname must specify a shared 
interprocess communication 


resource, and shi2_path must point 
to a NULL string. 


NetShareAdd ignores the value specified in the shi2_current_uses component of 
share_info_2. 


Related Information 
For information on: 


¢ Removing a list of shareable resources—See “NetShareDel” on page 3-347. 


e Listing the shareable resources of a server—See “NetShareEnum” on page 3-350. 
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NetShareCheck 


Syntax 


Return Codes 


The NetShareCheck (server, DOS) function queries as to whether a server is sharing 
a device. 


#include <netcons.h> 
#include <shares.h> 
#include <access.h> 


unsigned far pascal 
NetShareCheck(servername, devname, type) 


char far * servername; 
char far * devname; 
unsigned short far * type; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ devname points to an ASCIIZ string containing the name of the device to be 
checked. 


¢ type points to an unsigned short integer indicating the type of shared device, as 
defined in SHARES.H as follows: 


Manifest Value Meaning 
STYPE_DISKTREE 0 Disk drive. 
STYPE_PRINTQ 1 Spooler queue. 
STYPE_DEVICE 2 Serial device. 

STYPE_IPC 3 Interprocess communication 


device. 


The returned type value is valid only if NetShareCheck is successful. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR _NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_PARAMETER 87 The specified 


parameter is invalid. 
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Manifest 
ERROR_INVALID_LEVEL 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_ServerNotStarted 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR _WkstaNotStarted 


NERR _BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_NetNameNotFound 


NERR_DeviceNotShared 


NERR_InvalidComputer 


Value 
124 


2102 


2104 


2106 


2114 


2123 


2427 


2134 


2138 


2139 


2140 


2141 


2310 


2311 


2351 


Meaning 


The Level parameter is 
invalid. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


This shared resource 
does not exist. 


This device is not 
shared. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


e DosFreeSeg 


DosFsCtlh(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
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¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear. 


Remarks 
The NetShareCheck function returns successfully if a specified device is in the 


routing list of a spooler queue or serial device queue. 
Related Information 
For information on: 


¢ Reconfiguring the shareable resource of a server—See “NetShareSetInfo” on 
page 3-356. 


¢ Retrieving the status of a shared resource—See “NetShareGetInfo” on 
page 3-353. 
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NetShareDel 


Syntax 


Return Codes 


The NetShareDel (admin, server, DOS) function deletes a net name from the list of 
shared resources of a server. 


#include <netcons.h> 
#include <shares.h> 
#include <access.h> 


unsigned far pascal 

NetShareDel (servername, netname, reserved) 
char far * servername; 

char far * netname; 

unsigned short reserved; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ netname points to an .“SCIIZ string specifying the netname to be deleted. 


e reserved is 0. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_ INVALID PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
NERR_ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 
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Manifest Value Meaning 
NERR _ServerNotStarted 2114 The Server service has 


not been started. 


NERR_BufTooSmall 2123 The buffer is too small 


for fixed-length data. 


NERR_RemoteErr PAO A remote API error 


has occurred. 


NERR_OS2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 
NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 
NERR_InternalError 2140 An internal error has 
occurred. 
NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 
NERR_NetNameNotFound 2310 This shared resource 


does not exist. 


NERR_InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


AltSrvShareDel 

DosFsRamSemClear 

DosFreeSeg 

DosFsCtlh(NETTRANSACTION) 
DosFsCtlhKNULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 

DosGetProcAddr 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosLoadModule 


DosSemClear. 


When the NetShareDel function deletes a netname, all connections to the shared 
resource are disconnected. 
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Related Information 
For information on: 


e Adding a share on a server—See “NetShareAdd” on page 3-340. 


e Listing all connections to a shared resource—See “NetConnectionEnum” on 
page 3-78. 


e Listing the shareable resources of a server—See “NetShareEnum” on page 3-350. 
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NetShareEnum 
The NetShareEnum (partially admin, server, DOS) function retrieves share 
information about each shared resource on a server. 


Syntax 


#include <netcons.h> 
#include <shares.h> 
#include <access.h> 


unsigned far pascal 
NetShareEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 

char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ level specifies the level of detail (0, 1, or 2) returned in the share_info data 
structure. 


¢ buf points to the share_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 3 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR _ MORE DATA 


NERR_NetNotStarted 


NERR _ShareMem 


NERR_RemoteOnly 


NERR _ ServerNotStarted 


NERR_RemoteErr 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_InvalidComputer 


Value 
234 


2102 


2104 


2106 


2114 


2127 


2134 


2138 


2139 


2140 


2141 


2351 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


¢ DosFsCthNETTRANSACTION) 
¢ DosFsCth(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 


¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


e¢ DosSemClear. 
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Remarks 
If the /evel parameter of NetShareEnum is passed with the value 2, the calling 
application must have administrative privileges on the server. 


Related Information 


For information on retrieving information about a particular shared resource, see 
“NetShareGetInfo” on page 3-353. 
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NetShareGetinfo 


Syntax 


Return Codes 


The NetShareGetInfo (partially admin, server, DOS) retrieves information about a 
particular shared resource on a server. 


#include <netcons.h> 
#include <shares.h> 
#include <access.h> 


unsigned far pascal 
NetShareGetInfo(servername, netname, level, buf, 
buflen, totalavail) 


char far * servername; 
char far * netname; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ netname points to an ASCIIZ string containing the name of the share of interest. 


¢ level specifies the level of detail (0, 1, or 2) returned in the share_info data 
structure. 


¢ buf points to the share_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Manifest Value Meaning 
NERR_ SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient. memory is 
not available. 
ERROR _ NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_ PARAMETER 87 The specified . 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
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Manifest 
ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_NetNameNotFound 


NERR _InvalidComputer 


Value 
234 


2102 


2104 


2106 


2114 


2123 


2127 


2134 


2138 


2139 


2140 


2141 


2310 


2351 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


This shared resource 
does not exist. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsRamSemClear 


¢ DosFreeSeg 


DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
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¢ DosGetShrSeg[-ERROR FILE _NOT_FOUND] 
¢ DosSemClear. 
Remarks 


If the /evel parameter of NetShareGetInfo is passed with the value 2, the calling 
application must have administrative privileges on the server. 


Related Information 


For information on reconfiguring a shareable server resource, see “NetShareSetInfo” 
on page 3-356. 
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NetShareSetinfo 


The NetShareSetInfo (admin, server, DOS) function sets the parameters of a shared 


resource. 

Syntax 
#include <netcons.h> 
#include <shares.h> 


#include <access.h> 


unsigned far pascal 


NetShareSetInfo(servername, netname, level, buf, buflen, parmnum) 


char far * servername; 
char far * netname; 
short level; 
char far * buf ; 


unsigned short buflen; 
unsigned short parmnum; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 


Return Codes 


on which the function is to execute. A NULL pointer or string specifies a local 
server. 


netname points to an ASCIIZ string containing the netname of the resource to 
be set. 


level specifies the level of detail (1 or 2) provided by the share_info data 
structure. 


buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


buflen specifies the size (in bytes) of the buf memory area. 


parmnum specifies whether a specific component of the share_info data structure 
is being set, or the entire data structure. If parmnum is 0, then buf must contain 
a complete share_info data structure. Otherwise, parmnum must pass the ordinal 


position value for one of the following share_info_2 data structure components, 
as defined in SHARES.H as follows: 


Manifest Value Component 
SHIREMARK_ PARMNUM 4 shil_remark or 
shi2_remark 

SHI_MAX_USES_PARMNUM 6 shi2_max_uses 
Manifest Value Meaning 
NERR_ SUCCESS 0 No errors were 

encountered. 

ERROR_ACCESS DENIED 5 Administrative 


privilege is required. 


ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 


not available. 
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Manifest 


ERROR_NOT_SUPPORTED 


ERROR_INVALID PARAMETER 


ERROR_INVALID_NAME 


ERROR_INVALID_LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR _ServerNotStarted 


NERR_NoRoom 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


Value 
50 


87 


123 


124 


234 


2102 


2104 


2106 


2114 


2119 


2123 


2127 


2134 


2138 


2139 


2140 


Meaning 


This request is not 
supported by the 
network. 


The specified 
parameter is invalid. 


There is an incorrect 
character or incorrectly 
formed file system 
name. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The server is currently 
out of the requested 
resource. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 
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Manifest Value Meaning 


NERR _BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR_NameNotFound 2273 The message alias 


cannot be found on the 
local area network. 


NERR_NetNameNotFound 2310 This shared resource 
does not exist. 


NERR_InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCtlh(KNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosSemClear. 
Related Information 


For information on retrieving the status of a shareable server resource, see 
“NetShareGetInfo” on page 3-353. 


3-358 LAN Server Application Programmer’s Reference 


Spooler Category 


For information on the following functions, see the JBM Operating System/2 
Technical Reference Version 1.2 Programming Reference. 


SplQmAbort 
SplQmClose 
SplQmEndDoc 
SplQmOpen 
SplQmStartDoc 
SplQmWrite. 
The functions in the Spooler category provide the application access to spooler 


queue manager operations. These functions are provided by the base operating 
system and supported by the LAN Server across the network. 


Description 
For detailed descriptions of the above functions, refer to the IBM Operating 
System/2 Technical Reference Version 1.2 Programming Reference. 
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Statistics Category 
NetStatisticsGet2 (admin, DOS)—See “NetStatisticsGet2” on page 3-365. 


The functions in the Statistics category retrieve and clear the operating statistics for 
requesters and servers. They are used with the NETSTATS.H and NETCONS.H 
include files. 


Description 
The OS/2 LAN Requester/Server accumulates a set of operating statistics for 
requesters and servers from the time that a requester or server service is started. The 
NetStatisticsClear function can be called to clear the statistics. To retrieve the 
statistics, call the NetStatisticsGet2 function. 


Data Structures 
NetStatisticsGet2 function returns the statistics in the following data structures: 


Data Structure of Requester Statistics 

struct stat_workstation_0 { 
unsigned long stw0_start; 
unsigned long stwO_numNCB r; 
unsigned long stwO_numNCB s; 
unsigned long stwO_numNCB a; 
unsigned long stwQ_fiNCB_r; 
unsigned long stwO_fiNCB s; 
unsigned long stw0_fiNCB a; 
unsigned long stw0_fcNCB_r; 
unsigned long stwQ_fcNCB s; 
unsigned long stwQ_fcNCB a; 
unsigned long stw0_sesstart; 
unsigned long stw0_sessfailcon; 
unsigned long stwQ_sessbroke; 
unsigned long stw0_uses; 
unsigned long stw0_usefail; 
unsigned long stwO_autorec; 
unsigned long stwO_bytessent_r_high; 
unsigned long stw0_bytessent_r_low; 
unsigned long stw0_bytesrcvd_r_high; 

_unsigned long stwQ_bytesrcvd_r_low; 
unsigned long stw0O_bytessent_s_ high; 
unsigned long stw0_bytessent_s_low; 
unsigned long stw0_bytesrcvd_s_ high; 
unsigned long stw0_bytesrcvd_s_low; 
unsigned long stw0_bytessent_a_high; 
unsigned long stw0_bytessent_a_low; 
unsigned long stwO_bytesrcvd_a_high; 
unsigned long stwO_bytesrcvd_a_low; 
unsigned long stw0_reqbufneed; 
unsigned long stw0_bigbufneed; 

}; 


where: 


e start is the time that statistics collection started. This field indicates the date or 
time that the statistics were last cleared; that is, it indicates the time period over 
which the returned statistics were collected. 
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numNCB fields indicate the number of network control blocks (NCBs) issued 
from each source and include failed NCBs. To get the total successful NCBs 
issued it is necessary to subtract the numbers of failed NCBs. These numbers 
are held as follows in the fiNCB and fcNCB fields: 


— numNCB_r is the number of NCBs issued (redirector) 
— numNCB_s is the number of NCBs issued (server) 
— numNCB_a is the number of NCBs issued (application). 


SiNCB fields indicate the number of NCBs that failed at the time they were 
issued, for whatever reason. These NCBs are still included in the “total issued” 
count, as follows: 


— fiNCB_r is the number of NCBs that failed issue (redirector) 
— fiNCB_s is the number of NCBs that failed issue (server) 
— fiNCB_ais the number of NCBs that failed issue (application). 


JScNCB fields indicate the number of NCBs that failed after issue, at or before 
completion. These NCBs are still included in the “total issued” count, as 
follows: 


— fcNCB_r is the number of NCBs that failed completion (redirector) 
— fceNCB_s is the number of NCBs that failed completion (server) 

— fcNCB_a is the number of NCBs that failed completion (application). 
sessStart is the number of requester sessions started. 


sessfailcon is the number of requester session failures to connect, except those 
that failed due to “name not found.” 


sessbroke is the number of failures of requester sessions, after the session was 
established. 


uses is the number of requester uses. 


usefail is the number of requester use failures. This is a count of failed 
tree-connects, when a server is found but the resources were not found. 


autorec is the number of requester auto-connects. 


The following 12 fields form six guad-WORDs, which contain very large 
counters. The high DWORD of each is the value divided by 2%32, while the low 
DWORD is the value modulo 2%32. A quad-WORD is a data area with the size 
twice as large as a double word. 


These fields count total bytes in all NCBs sent and received for all three 
categories. Server information is included to provide an accurate total. 


Note: For all the NCB-related and bytes-count counters: 


The suffix _r indicates redirector. These NCBs are issued by the 
redirector as part of the normal process of maintaining remote network 
connections. 


Those with the suffix _s are server-related, sent by the redirector on 
behalf of the server to maintain shared resource connections. 


Chapter 3. API Function Descriptions 3-361 


Those with the suffix _a are application-generated NCBs, which may be 
caused by applications calling NetBiosSubmit, use of second-class 
mailslots, server announcements (sending and receiving), and so on. 


— bytessent_r_hiis the number of requester bytes sent to the network (high 
DWORD). 


— bytessent_r_lo is the number of requester bytes sent to the network (low 
DWORD). 


— bytesrcvd_r_hiis the number of requester bytes received from the network 
(high DWORD). 


— bytesrcvd_r_lo is the number of requester bytes received from the network 
(low DWORD). 


— bytessent_shi is the number of server bytes sent to the network (high 
DWORD). 


— bytessent_s_lo is the number of server bytes sent to the network (low 
DWORD). 


— bytesrcvd_s_hi is the number of requester bytes received from the network 
(high DWORD). 


— bytesrcvd_s_lo is the number of requester bytes received from the network 
(low DWORD). 


— bytessent_a_hi is the number of application bytes sent to the network (high 
DWORD). 


—  bytessent_a_lo is the number of application bytes sent to the network (low 
DWORD). 


—  bytesrcvd_a_hi is the number of application bytes received from the network 
(high DWORD). 


— bytesrcvd_a_lo is the number of application bytes received from the network 
(low DWORD). 


¢ reqbufneed is the number of times that the requester required a request buffer 
but failed to allocate one. This indicates that the parameters of the requester 
may need adjustment. 


e bigbufneed is the number of times the requester required a big buffer but failed 
to allocate one. This indicates that the parameters of the requester may need 
adjustment. 


Note: A value of -1 or OXFFFFFFFF for any field means that information is not 
available. A value of -2 or OXFFFFFFFE means that the field has 
overflowed. 
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Data Structure of Server Statistics 


struct stat_server_0 { 


ie 


unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 


where: 


long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 


stsO_ start; 
sts0O_fopens; 
stsQ_devopens; 
sts0_jobsqueued; 
sts0_sopens; 
stsO_stimedout; 
stsO0_serrorout; 
stsO_pwerrors; 
stsO_permerrors; 
sts0_syserrors; 
sts0_bytessent_high; 
sts0_bytessent_low; 
sts0_bytesrcvd_high; 
sts0_bytesrcvd_low; 
stwO_avresponse; 
stw0_reqbufneed; 
stwO_bigbufneed; 


start is the time statistics collection started. This field indicates the date and 
time that the statistics were last cleared; that is, it indicates the time period over 
which the returned statistics were collected. 


fopens is the number of server file opens. This includes opens of named pipes. 


devopens is the number of server device opens. 


Jobsqueued is the number of server print jobs spooled. 


sopens is the number of server session starts. 


stimedout is the number of server session auto-disconnects. 


serrorout is the number of server sessions errored out. 


pwerrors is the number of server password violations. 


permerrors is the number of server access permission errors. 


syserrors is the number of server system errors. 


The following 4 fields form two quad-WORDs that contain very large counters. 
The high DWORD of each is the value divided by 232, while the Jow DWORD 
is the value modulo 2%32. 


— bytessent_high is the number of server bytes sent to the network (high 
DWORD) 


— bytessent_low is the number of server bytes sent to the network (low 
DWORD) 


— bytesrcvd_high is the number of server bytes received from the network (high 
DWORD) 


—  bytesrcvd_low is the number of server bytes received from the network (low 
DWORD). 


avresponse is the average server response time in milliseconds. 
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¢ reqbufneed is the number of times the server required a request buffer but failed 
to allocate one. This indicates that the parameters of the server may need 
adjustment. 


¢ bigbufneed is the number of times the server required a big buffer but failed to 
allocate one. This indicates that the parameters of the server may need 
adjustment. 


Note: A value of -1 or OXFFFFFFFF for any field means that information is not 
available. A value of -2 or OXFFFFFFFE means that the field has 
overflowed. 
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NetStatisticsGet2 


Syntax 


The NetStatisticsGet2 (admin, DOS) function retrieves and optionally clears 
operating statistics for a service. 


#include <netcons.h> 
#include <netstats.h> 


unsigned far pascal 
NetStatisticsGet2(servername, servicename, reserved, level, options, 


buf, buflen, totalavail) 


char far * servername; 
char far * servicename; 
unsigned long reserved; 
short levels; 
unsigned long options 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 


where: 


servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


servicename is the ASCIIZ service name for which to get the statistics. 


For the OS/2 LAN Requester/Server version 1.2 program, only SERVER and 
REQUESTER are allowed for the servicename. Other names will produce the 
ERROR _NOT_SUPPORTED error code. If the server statistics are requested 
and the server is not running, the error code returned is 

NERR ServiceNotInstalled. 


reserved must be zero. 


level specifies the level of detail (0) returned by the stat_workstation_0 or the 
stat_server_O data structure. 


The valid values for level depend on the value of servicename. The current valid 
value for REQUESTER or SERVER is 0. 


options are the options flags. 


The options parameter is bitmapped as follows: 


Bit Mask Symbol Meaning 

0 0x1 STATSOPT_CLR Clear statistics after 
retrieval 

1-31 Must be zero 


The option to clear the statistics allows automatic Get and Clear operations, 
which allows an atomic get and clear operation, which allows an application that 
is compiling cumulative numbers to make sure that no data slips by in the time 
between the Get operation and the Clear operation. 


buf points to the returned stat_workstation_0 or the stat_server_O data structure. 
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Return Codes 


¢ buflen specifies the size (in bytes) of buf. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 


information that were available. 


Manifest 
NERR_SUCCESS 


ERROR_ACCESS_ DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR _NETWORK_ACCESS DENIED 


ERROR_INVALID PARAMETER 


ERROR_INVALID_LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


NERR _ShareMem 


NERR ServerNotStarted 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 
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Value 


65 


87 


124 


234 


2102 


2104 


2114 


2123 


2134 


2138 


2139 


2140 


2141 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 


Sufficient memory is 
not available. 


Network access is 
denied. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


Remarks 


Manifest Value Meaning 


NERR ServiceNotInstalled 2184 The service has not 
been started. 

NERR_BadServiceName 2185 The service name is 
invalid. 

NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


DosFsRamSemClear 

DosFreeSeg 

DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 


DosSemClear. 


This API returns a full data structure. As with other GetInfo calls, the error 
NERR_BuffTooSmall is returned if the supplied buffer is too small for the required 
data. 


If the service name specified is REQUESTER, then stat_workstation_0 is returned to 
buf. If the service name specified is SERVER, then stat_server is returned to buf. 
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Use Category 


Description 


NetUseAdd (admin, DOS)—See “NetUseAdd” on page 3-372. 
NetUseDel (admin, DOS)—See “NetUseDel” on page 3-375. 
NetUseEnum (admin, DOS)—See “NetUseEnum” on page 3-378. 
NetUseGetInfo (admin, DOS)—See “NetUseGetInfo” on page 3-380. 


The functions in the Use category examine or control connections (uses) between 
requesters and servers. Administrative privilege is required to call them remotely. 
They are used with the USE.H and NETCONS.H include files. 


The NetUseAdd function establishes a connection between a local computer and a 
resource shared on a server by redirecting a NULL or local device name to a shared 
resource on that remote server. The following types of connections can be made: 


e Device name connections, which can only be explicit 


e Universal naming convention (UNC) connections, which can be explicit or 
implicit. 


To establish an explicit device name connection, NetUseAdd redirects a local device 
name to the netname of a remote server resource (\\servername\netname). Once a 
device name connection is made, users or applications can use the remote resource 
by specifying the local device name. 


UNC connections can be explicit, created by the NetUseAdd function, or implicit, 
made by way of an OS/2 function (responsible for the connection). Once a UNC 
connection is established, users or programs can access the remote resource by 
specifying just the netname of the resource. 


To establish an explicit UNC connection, NetUseAdd redirects a NULL device 
name to the netname of a remote server resource. 


To establish an implicit UNC connection, an application passes the netname of the 
resource to any one of the OS/2 functions that accept netnames (such as the 
DosOpen function). The UNC name will be understood by the OS/2 function and a 
connection will be made to the specified netname. All further requests on this 
connection require the full netname. 


Note: Connections are to be distinguished from sessions. A session is a path 
between a requester and a server, established the first time a requester makes a 
connection with one of the shared resources of the server. All further connections 
between the requester and the server are part of this same session until ended by 
calling the NetSessionDel function. 
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As an example of how the three types of connections work, consider the following 
examples: 


¢ Explicit device name connection. Assume an application redirected the local 
device name d: to the netname \\develop\srcdrv by calling the NetUseAdd 
function as shown: 


strncpy (buf.uil_local, "d:", 3); 
retcode = NetUseAdd ( NULL, 1, buf, BUFLEN ); 


To access files on this resource, an application need only specify the redirected 
device name and the name of the file, as shown: 


retcode=system("type d:\\read.me") ; 


¢ Explicit UNC connection. Assume an application redirected a NULL device 
name to the remote resource \\develop\srcdrv by calling the NetUseAdd function, 
as shown: 


strncpy (buf.uil_local, "", 3); 
retcode = NetUseAdd ( NULL, 1, buf, BUFLEN ); 


To display the contents of the READ.ME file on the resource \\develop\srcdry, 
an application can also just specify the name of the resource with the following 
command: 


retcode=system("type \\\\develop\\srcdrv\\read.me") ; 


Note that this does not create a new connection to the resource, as an implicit 
UNC connection would if no NetUseAdd function was called. 


¢ Implicit UNC connection. An implicit connection is made by a call to an OS/2 
function and by passing the remote netname as part of a parameter. For 
example, the following call to DosOpen establishes an implicit UNC connection 
to the remote resource \\develop\srcdrv and opens file.1: 


retcode = DosOpen ("\\\\develop 
\\sredrv\\file.1, ...")3 


A password must be supplied the first time a universal naming convention 
(UNC) connection is made between a local or NULL device name and a remote 
resource if the resource is on a server running in user-level security. Further 
connections to the same server do not require a password because the password 
is associated with the same session. 


DOS Considerations 
Under DOS, the functions can be executed only on a remote server. Attempting to 
execute the functions on a local requester returns NERR_RemoteOnly. 


Data Structures ; 
The data structures used by the NetUseAdd, NetUseEnum, and NetUseGet 
functions are described immediately following the syntax descriptions for each 
function. 


Use Information (Level 0) 


struct use_info 0 { 


char uid_local [DEVLEN+1] ; 
char uid_pad_1; 

char far * ui0_remote; 

}; 
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where: 


¢ ui0_local is an ASCIIZ string specifying the local device name (such as E:, LPT1, 
or COM1) being redirected to the shared resource. 


¢ ui0_pad_]1 WORD-aligns the data structure components. 


¢ ui0_remote points to an ASCIIZ string containing the netname of the remote 
resource being accessed. The string must be in the form \\servername\netname. 


Use Information (Level 1) 


sruct use_info_1 { 

char uil_local [DEVLEN+1] ; 
char uil_pad_l; 

char far * uil_remote; 

char far * uil_password; 
unsigned char uil_status; 

unsigned char uil_asg type; 
unsigned char uil_refcount; 
unsigned char uil_usecount; 

}; 


where: 


e uil_local is an ASCYIZ string specifying the local device name being redirected 
to the shared resource. 


¢ uil_pad_] WORD-aligns the data structure components. 


¢ uil_remote points to an ASCIIZ string specifying the UNC name of the remote 
resource being accessed. The string must be in the form \\servername\netname. 


¢ uil_password is a reserved field; it must be NULL. 


° uil_status specifies the status of the connection. Seven possible values for 
uil_status are defined in USE.H, as follows: 


Manifest Value Meaning 
USE_OK 0 Connection valid. 
USE_PAUSED l Paused by local requester. 


USE_SESSLOST 2 Session removed. 
USE_DISCONN Z Connection disconnected 
USE_NETERR 3 Network error. 
USE_CONN 4 Connection being made. 
USE_RECONN p) Reconnecting. 


¢ uil_asg_type specifies the type of remote resource being accessed. Five types of 
resources are defined in USE.H, as follows: 
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Manifest Value Meaning 


USE_WILDCARD -1 Matches the type of the share of 
the server (Wildcards are only 
used when uil_local is a NULL 


string). 
USE_DISKDEV 0 Disk device. 
USE_SPOOLDEV 1 Spooled printer. 
USE_CHARDEV 2 Serial device. 
USE_IPC 3 Interprocess communication 
(IPC). 


The asg_type field indicates the sort of device to use the resource “as.” It can be 
any of the previously listed values under asg_type, or it can be set to 
USE_WILDCARD (-1), only for a connection with a NULL local device. A 
connection that maps a local device to the resource must use one of the other 
four values defined in asg_type. 


uil_refcount indicates the number of files, directories, and other processes that 
are open on the remote resource. 


uil_usecount indicates the number of explicit connections (redirection of a local 
device name) or implicit UNC connections (redirection of a NULL local device 
name) that are established with the resource. 


If both an explicit and an implicit connection exists between a requester and a 
resource, the usecount of the server is 1 and the usecount of the requester is 2. 
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‘NetUseAdd 


Syntax 


Return Codes 


The NetUseAdd (admin, DOS) function establishes a connection between a local or 
NULL device name and shared resource by redirecting the local or NULL (UNC) 
device name to the shared resource. 


#include <netcons.h> 
#include <use.h> 


unsigned far pascal 
NetUseAdd(servername, level, buf, buflen) 


char far * servername; 
short levels 
char far * buf; 


unsigned short buflen; 
where: 


* servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ level specifies the level of detail (1) for the use_info_] data structure. 
¢ buf points to the use_info_] data structure. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 2 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR_NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_BAD_DEV_TYPE 66 This network device 
type is incorrect. 
ERROR_BAD_NET_NAME 67 This network name 
cannot be found. 
ERROR_ALREADY_ASSIGNED 85 Duplicate redirection. 
ERROR_INVALID_PASSWORD 86 The specified password 
is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 


3-372 LAN Server Application Programmer’s Reference 


Manifest 
ERROR_MORE DATA 


NERR _NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR ServerNotStarted 


NERR _BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_UseNotFound 


NERR_BadAsgType 


NERR_DevicelIsShared 


NERR_DeviceNotShared 


NERR InvalidComputer 


NERR _LocalDrive 


Value 
234 


2102 


2104 


2106 


2114 


2123 


2127 


2134 


2138 


2139 


2140 


2141 


2250 


2251 


2252 


2311 


2351 


2415 


Meaning 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The connection cannot 
be found. 


This asg_type is 
invalid. 


This device is already 
being shared. 


This device is not 
shared. 


The specified computer 
name is invalid. 


Drive in local use. 
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Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsRamSemClear 
¢ DosFsRamSemRequest 
¢ DosFreeSeg 
¢ DosFsAttach 
¢ DosFsCtlh(NETTRANSACTION) 
¢ DosFsCtl(NIOCSETASGLIST) 
¢ DosFsCthKNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg 
¢ DosSemClear 
¢ DosSemRequest 
e redir.(NIOCSETASGLIST1_1). 

Remarks 
A local device name can be redirected to only one shared resource at a time. To 


establish a new direction for a redirected device, an application must first delete the 
existing connection by calling the NetUseDel function. 


A COM or LPT device can be redirected even if it is already opened. Redirecting 
the device has no effect on the handle of the device if it is already open. However, 
subsequent openings will return a handle to the remote device to which the local 
device was redirected. 


When a server is running user-level or share-level security, The uil_password needed 
to access a shared resource can be provided in the following ways: 
e A non-NULL string specifies the password 


¢ A NULL pointer forces the OS/2 LAN Requester/Server software to use the 
same password given to the logon function 


¢ A NULL string indicates that no password is provided. 


NetUseAdd ignores the uil_status, uil_refcount, and uil_usecount components in the 
use_info_I data structure. 


If a call to NetUseAdd duplicates an existing connection, the usecount component of 
the use_info_1 data structure is incremented and the function succeeds, returning 
NERR_Success. 


Related Information 
For information on: 


¢ Disconnecting a device from a shared resource—See “NetUseDel” on 
page 3-375. 


e Listing all devices redirected to a shared resource—See “NetUseEnum” on 
page 3-378. 
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NetUseDel 


Syntax 


Return Codes 


The NetUseDel (admin, DOS) function ends a connection between a local or UNC 
device name and a shared resource. 


#include <netcons.h> 
#include <use.h> 


unsigned far pascal 

NetUseDel (servername, devicename, forceflag) 
char far * servername; 

char far * devicename; 

short forceflag; 


where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


e devicename points to an ASCIIZ string indicating the local device name that was 
redirected to the shared resource. 


e forceflag is one of three values specifying three types of disconnection. As 
defined in USE.H, the following options are available: 


Manifest Value Meaning 


USE_NOFORCE 0 Maintains the connection in a 
dormant state, decrementing 
usecount. A dormant session 
can quickly be activated as soon 
as reconnection is needed, 
improving system performance. 


USE_FORCE i Connection is removed only if 
no file, directory, or drive is 
opened. usecount is decremented 
(for a local device name 
connection) and forced to 0 (for 
a UNC connection). 


USE_LOTS_OF_FORCE 2 All files, directories, and drives 
open on the connection are 
forced closed. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED > Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 


not available. 
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Manifest 
ERROR_INVALID_DRIVE 


ERROR_NOT_SUPPORTED 


ERROR_BAD_DEV_TYPE 


ERROR_BAD_NET_NAME 


ERROR_INVALID_PARAMETER 


ERROR_PROTECTION_VIOLATION 


NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IloctlError 


NERR_WkstaNotStarted 


NERR InternalError 


NERR _BadTransactConfig 


NERR InvalidComputer 


NERR_OpenFiles 


Value 
15 


50 


66 


67 


87 


115 


2123 


2127 


2134 


2138 


2140 


2141 


2351 


2401 


Meaning 


The specified drive is 
not valid. 


This request is not 
supported by the 
network. 


This network device 
type is incorrect. 


This network name 
cannot be found. 


The specified 
parameter is invalid. 


Incorrect user virtual 
address. 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The specified computer 
name is invalid. 


There are open files on 
the connection. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosFsAttach 

¢ DosFsCtlh(NETTRANSACTION) 
¢ DosFsCtl(NIOCSETASGLIST) 
¢ DosFsCthKNULLTRANSACT) 
e redir.(NIOCSETASGLIST1_1). 
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Related Information 
For information on: 


e Listing all local device names redirected to a shared resource—See 
“NetUseEnum” on page 3-378. 


¢ Redirecting a local device name to a shared resource—See “NetUseAdd” on 
page 3-372. 
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NetUseEnum 
The NetUseEnum (admin, DOS) function lists all current connections between the 
local computer and resources on a remote server. 


Syntax 


#include <netcons.h> 
#include <use.h> 


unsigned far pascal 
NetUseEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflens 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


e level specifies the level of detail (0 or 1) returned by the use_info data structure. 
¢ buf points to the use_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_DRIVE 15 The specified drive is 
not valid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest Value Meaning 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 

NERR_BufTooSmall 2123 The buffer is too small 
for fixed-length data. 

NERR_RemoteErr 2127 A remote API error 
has occurred. 

NERR_OS2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 

NERR_BrowserNotStarted 2139 The requested 
information is not 
available. 

NERR _InternalError 2140 An internal error has 
occurred. 

NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 

NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosFsCtlh(NETTRANSACTION) 
¢ DosFsCtl(NIOCSETASGLIST) 
¢ DosDevIOCtl(NIOCSETASGLIST1L_1) 
¢ DosFsCthNULLTRANSACT) 
e redir.(NIOCSETASGLIST1_1). 

Related Information 

For information on: 

¢ Listing the shared resources of a server—See “NetShareEnum” on page 3-350. 


¢ Retrieving the status of a local device name—See “NetUseGetInfo” on 
page 3-380. 
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NetUseGetinfo 


The NetUseGetInfo (admin, DOS) function retrieves information about a connection 
between a local device name.and a shared resource. 


Syntax 


#include <netcons.h> 
#include <use.h> 


unsigned far pascal 
NetUseGetInfo(servername, netname, level, 
buf, buflen, totalavail) 


char far * servername; 
char far * netname; 
short levels 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
computer. 


¢ netname points to an ASCIIZ string containing the name of the redirected device 
name or UNC name for the resource. 


e level specifies the level of detail (0 or 1) returned in the use_info data structure. 
¢ buf points to the use_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
| privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_BufTooSmall 


NERR_RemoteErr 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_UseNotFound 


NERR_InvalidComputer 


Value 
2123 


2IZT 


2134 


2138 


2139 


2140 


2141 


2250 


2351 


Meaning 


The buffer is too small 
for fixed-length data. 


A remote API error 
has occurred. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The connection cannot 
be found. 


The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosDevIOCth(NIOCGETASGLIATI_1) 


¢ DosFsCtl(NETTRANSACTION) 
¢ DosFsCtl(NIOCSETASGLIST) 
* DosFsCtl(NULLTRANSACT) 


e redir. NIOCSETASGLIST1_1 [ERROR _NO_MORE FILES]. 


Remarks 


The NetUseGetInfo function returns the uil_password component as a NULL 
pointer, so users or applications cannot determine the password of another user or 


application. 


Related Information 
For information on: 


e Listing all connections to a shared resource—See “NetUseEnum” on page 3-378. 


e Listing the shared resources of a server—See “NetShareEnum” on page 3-350. 


Chapter 3. API Function Descriptions 3-381 


User Category 


Description 


NetUserAdd (admin, DOS)—See “NetUserAdd” on page 3-397. 

NetUserDel (admin, DOS)—See “NetUserDel” on page 3-401. 

NetUserEnum (partially admin, DOS)—See “NetUserEnum” on page 3-404. 
NetUserGetGroups (partially admin, DOS)—See “NetUserGetGroups” on page 3-407. 
NetUserGetInfo (partially admin, DOS)—See “NetUserGetInfo” on page 3-410. 


NetUserModalsGet (partially admin, DOS)—See “NetUserModalsGet” on 
page 3-413. 


NetUserModalsSet (admin, DOS)—See “NetUserModalsSet” on page 3-416. 
NetUserPasswordSet (DOS)—See “NetUserPasswordSet” on page 3-419. 
NetUserSetGroups (admin, DOS)—See “NetUserSetGroups” on page 3-423. 
NetUserSetInfo (partially admin, DOS)—See “NetUserSetInfo” on page 3-426. 
NetUserValidate2 (/ocal)—See “NetUserValidate2” on page 3-431. 


The functions in the User category control a user’s account in the user accounts 
subsystem (UAS) database. They are used with the ACCESS.H and NETCONS.H 
include files. 


In the UAS, each user or application that accesses the resources must have a user 
account in the system. The system uses this account to verify that the user or 
application has permission to connect to any shared resource. A user’s account is set 
up by calling the NetUserAdd function. There are three types of information in a 
user’s account: 


e¢ One type can be set only by the administrator 
e Another can be set by the owner of the account 


e The third can be set only by the system. 


The following user account information can be set by the administrator only: 


¢ Account Name—The name used to log on (for example, JSMITH). 

¢ Full Name Field—The full name of the user (for example, John Smith, Jr.). This 
field can be up to MAXCOMMENTSZ + 1 bytes long. A NULL pointer is 
treated as a null string. 

¢ Comment—The comment associated with an account (for example, Vice 
President). It can contain any text and can be up to MAXCOMMENTSZ + 1 
bytes. 

e Parms—The drive of the user’s home directory. 

¢ Home Directory—The network directory (absolute, UNC, or local path) for the 
user’s files. The field length can be up to PATHLEN bytes. 

¢ Account Disabled—When set, no one can log on using this account. 
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e Privilege Level—An account can have one of three levels of privilege: GUEST, 
USER, or ADMIN. Privilege level affects the default rights of an account to 
access resources and to call APIs remotely. 

¢ Logon Script Flag—Must be TRUE for this release. 

¢ Logon Script Path—The path name of the user’s logon script. It must be a 
relative path, and the path is relative to the NETLOGON service SCRIPTS 
path. This field can be up to PATHLEN bytes long, and a NULL pointer is 
treated as a null string. the script can be a .pro, a .cmd (or .bat), an .exe or a 
.com, or it can have no extension which is defaulted to .cmd (or .bat) file. 

e Account Expiration Date—Logon is disabled after specified date. 

e List of Authorized Requesters—Account can only log on from listed PCs; the list 
may include zero to eight stations. Zero stations means ALL. 

e Logon Hours—1 hour granularity, hours specified for each day of the week. A 
NULL pointer means ALL for NetUserAdd calls but means DONT_CHANGE 
for NetUserSetInfo calls. 

¢ Home Directory Required—When this bit is set, UAS requires that the Home 
Directory field must not be NULL. 

¢ Password Not Required—When this bit is set, the account can have a NULL 
password even if the Minumum Password Length for the system is greater than 
0. 

¢ Maximum Storage Allotment—Specifies the limit in KB on the home directory. 

¢ User Can Not Change Password—This flag restricts the user from changing the 
password on his account. 

e¢ Logon server—The name of the server which tracks logon and logoff for the 
account. It should be NULL for this release. NULL means that the domain 
controller validates the logon requests. 


The following fields can be set by a user (or by an administrator) for the user’s own 
account only: 


¢ Encrypted Password. 

¢ User Comment—A user-settable comment. This field can be up to 
MAXCOMMENTSZ + 1 bytes long. A NULL pointer is treated as a null 
string. 

¢ Parms—An ASCIIZ string for application use. 

¢ Country Code—The OS/2 country code for the language choice of the user. This 
is used by the OS/2 LAN Requester/Server software to generate messages in the 
appropriate language whenever possible. 

¢ Code Page—The code page of the OS/2 program for national language support. 


The following fields are automatically set by the Accounts System and are not 
directly set by an administrator or user: 


¢ Date Password Last Changed.—This field is ignored by NetUserAdd and 
NetUserSetInfo calls. 
¢ Recent Passwords—The eight most recent encrypted passwords for this account. 


When a user or application requests access to any shared resource, the OS/2 LAN 
Requester/Server software checks to see whether there is an appropriate account. 
An application can do this by calling the NetUserValidate2 function to search for a 
valid account with a particular user name and password combination. 


If the account is found, the application then can check to see whether it is currently 
enabled by calling the NetUserGetInfo function and examining the flags that are set. 
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The OS/2 LAN Requester/Server software then checks the user’s privilege level. 
Depending on the parameter, the request to access a resource is immediately 
accepted, if the user has been given administrative privileges, or processing 
continues. 


Administrative privileges grant the broadest access to the domain, giving permission 
to execute all administrative functions, and complete access to the shared and 
non-shared resources of a server. 


If the user does not have administrative privileges, the OS/2 LAN Requester/Server 
software checks the resource’s access permission record to see whether the user has 
the proper permissions to use that particular resource (see “Access Permission 
Category” on page 3-2). 


Each time an account that has either administrative or user privileges is established 
by calling the NetUserAdd function, the OS/2 LAN Requester/Server software 
automatically adds a new account to the special group. At this time, the user 
inherits all permissions assigned to that special group. 


An application can change a user’s current privileges by calling the NetUserSetInfo 
function. Or it can change the user’s permissions by modifying that user’s group 
accounts (see “Group Category” on page 3-110). Individually assigned user 
permissions take precedence over group permissions assignments. An application 
can verify which groups a user belongs to by calling the NetUserGetGroups 
function. This function returns a list of group names. 


To find out how to change individual permission settings for members of one of the 
the special group, see “Access Permission Category” on page 3-2. 


When a user account is no longer needed, the NetUserDel function can be called to 
eliminate the account from the system. Once the account is removed, the user can 
no longer access the system. 


If an account does not have a password, any password (or none) is treated as a 
match for account validation. 


UAS modals can be used for global settings of password policy within the account 
system database. None of the system-wide password characteristics are enforced for 
accounts that do not require passwords. 


It is recommended that passwords be entered in uppercase characters. The password 
of a user account is case-sensitive at the API level, and lowercase characters in the 
password makes the user ID unavailable at the command-line interface and through 
the user profile management (UPM) full-screen interface. 


The user’s password is confidential and is not returned when the NetUserEnum or 
NetUserGetInfo function is called; a string of spaces is substituted for any password 
that is requested. The password is initially assigned when NetUserAdd is called. 
NetUserPasswordSet can be used by any user or application to change their own 
password, if the current password can be supplied. To verify an existing user 
account with a specified password, call NetUserValidate2. The NetUserSetInfo 
function can set the password and other components of a user account. 
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DOS Considerations 
The NetUserPasswordSet function controls a user’s password account in a domain. 
NetUserPasswordSet can be executed only on a remote server. Attempting to 
execute it on a local requester returns NERR_RemoteOnly. 


Data Structures 
There are three types of data structures in the User category: user account data 
structures, user modal data structures, and user validation data structures. The first 
is for user account information, the second is a user modal data structure, and the 
third is a user validation data structure. 


User Account Data Structures 
The data structures described here represent levels of detail available for the 
functions that define or return individual user accounts. The NetUserAdd, 
NetUserEnum, NetUserGetInfo, and NetUserSetInfo functions use user_info_0, 
user_info_1, user_info_2, user_info_10 or user_info_11, depending on whether their 
level parameter is 0, 1, 2, 10 or 11. 


NetUserGetGroups returns a very simple group_info_0 data structure, which is 
described following the syntax section of the function. 


User Account information (Level 0) 


struct user_info_0 { 
char usri@_name[UNLEN+1]; 
}3 


where: 


¢ usri0_name specifies the name of the user. 


User Account Information (Level 1) 


struct user_info 1 { 


char usril_name[UNLEN+1] ; 
char usril_pad_1; 
char usril_password [ENCRYPTED _PWLEN] ; 
long usril_password_age; 
unsigned short usril_priv; 
char far * usril_home_dir; 
char far * usril_comment; . 
unsigned short usril_flags; 
char far * usril_script_path; 
}; 
where: 


e usril_name specifies name of the user. 
e usril_pad_1 is for WORD-alignment of fields in the data structure. 


e usril_password is the password of a usril_name. The NetUserEnum and 
NetUserGetInfo functions return a string of spaces to maintain password 
security. The string can be NULL. 


e usril_password_age indicates the number of seconds that have passed since 
usril_password last changed: 
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e usril_priv is one of three values indicating the level of privilege assigned 
usril_name. The ACCESS.H include file defines these values as follows: 


Manifest Value Privilege 
USER_PRIV_GUEST 0 Guest 
USER_PRIV_USER 1 User 
USER_PRIV_ADMIN Z Administrator 


¢ usril_home_dir points to an ASCIIZ string containing the path name of the 


user_name’s home directory. The string can be NULL. 


¢ usril_comment points to an optional ASCIIZ string containing an optional 


comment or remark about the user. The string can be NULL. 


e usril_flags is one of the following values that determine whether or not a logon 
script is to be executed, and whether the user’s account is enabled. usril_flags is 


defined in ACCESS.H as follows: 


Manifest Bit 
Mask 
UF_SCRIPT 0x1 
UF_ACCOUNTDISABLE 0x2 
UF_HOMEDIR_ REQUIRED Ox8 
UF_PASSWD_NOTREQD 0x20 
UF_PASSWD_CANT_CHANGE 0x40 


Meaning 


Must be 1. Logon 
script enabled. 


If 1, user’s account 
disabled. 


If 1, home 
directory required. 


If 1, password not 
required. 


If 1, user cannot 
change password. 


e usril_script_path points to an ASCIIZ string indicating the path name of the 
user’s logon script (.cmd or .pro file). The string can be NULL. 
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User Account Information (Level 2): Information level 2 is needed to accomodate 
additional information for the UAS database. It will be an extension of user_info_1 
as shown in the following example: 


struct user_info_2 { 


char usri2_name[UNLEN+1] ; 
char usri2_pad_1; 
char usri2_password[ENCRYPTED_PWLEN] ; 
long usri2_password_age; 
unsigned short usri2_priv; 
char far * usri2_home_dir; 
char far * usri2_comment ; 
unsigned short usri2_flags; 
char far * usri2_script_path; 
unsigned long usri2_auth_flags; 
char far * usri2_full_name; 
char far * usri2_usr_comment; 
char far * usri2_parms; 
char far * usri2Z_workstations; 
long usri2_last_logon; 
Tong usri2_last_logoff; 
long usri2_acct_expires; 
unsigned long usri2_max_storage; 
unsigned short usri2_units_per_week; 
unsigned char far * usri2_logon_hours; 
unsigned short usri2_bad_pw_count; 
unsigned short usri2_num_logons; 
char far * usri2_logon_server; 
unsigned short usri2_country_code; 
unsigned short usri2_code_page; 

}; 

where: 


¢ usri2_name specifies name of the user. 
e usri2_pad_l is for WORD-alignment of fields in the data structure. 


¢ usri2_password is the password of a usril_name. The NetUserEnum and 
NetUserGetInfo functions return a string of spaces to maintain password 
security. The string can be NULL. 


¢ usri2_password_age indicates the number of seconds that have passed since 
usril_password last changed. 


¢ usri2_priv is one of three values indicating the level of privilege assigned 
usril_name. The ACCESS.H include file defines these values as follows: 


Manifest Value Privilege 
USER_PRIV_GUEST 0 Guest 
USER_PRIV_USER 1 User 
USER_PRIV_ADMIN Z Administrator 


¢ usri2_home_dir points to an ASCIIZ string containing the path name of the 
user_name’s home directory. The string can be NULL. 


° usri2_comment points to an optional ASCIIZ string containing an optional 
comment or remark about the user. The string can be NULL. 
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e usri2_flags is one of the following values that determine whether or not a logon 


script is to be executed, and whether the user’s account is enabled. usri2_flags is 
defined in ACCESS.H as follows: 


Manifest Bit Meaning 
Mask 
UF_SCRIPT Ox1 Must be 1. Logon 
script enabled. 
UF_ACCOUNTDISABLE 0x2 If 1, user’s account 
disabled. 
UF_HOMEDIR_REQUIRED 0x8 If 1, home 
directory required. 
UF_PASSWD_NOTREQD 0x20 If 1, password not 
required. 
UF_PASSWD_CANT_CHANGE 0x40 If 1, user cannot 


change password. 


¢ usri2_script_path points to an ASCIIZ string indicating the path name of the 
user’s logon script (.cmd or .pro file). The string can be NULL. 


° auth_flags is reserved. 


¢ full_name points to an ASCIIZ string containing the full name of the user. The 
string can be NULL. 


© usr_comment points to an ASCIIZ string which is a user-settable field. The string 
can be NULL. 


¢ parms points to an ASCIIZ string containing the name of the user’s home 
directory. The string can be NULL. 


¢ workstations is a list of requesters from which a user is permitted to log on. A 
NULL string means all requesters are allowed. (To disallow logon, the account 
disabled flag must be set.) Up to 8 requesters may be specified. The list of 
requesters can include IBM NETBIOS permanent names, which are listed as 
machine IDs, consisting of 12 hexidecimal digits. IBM NETBIOS permanent 
names are entered in the requester as shown as follows: 


16DF.02AC.7DE9 


¢ Jlast_logon is the time and date (seconds since 1/1/70) when the last logon 
occurred. Zero means unknown. This field can be set only by the system. 


¢ last_logoff is the time and date (seconds since 1/1/70) when the last logoff 
occurred. Zero means unknown. This field can be set only by the system. 


¢ acct_expires is the time and date (seconds since 1/1/70) when the account will 
expire. An expired account is the equivalent of a disabled account. An entry of 
OxFFFFFFFF means that the account will never expire. 


*¢ max_storage is a maximum storage allotted for the home directory. Units are K 
bytes. An entry of OXFFFFFFFF means that the account will never expire. 


¢ units_per_week is the number of equal-length time units into which the week is 
divided. This value is used to compute the length of the bit string in 
logon_hours. It must be UNITS_PER_WEEK (168) for this release. This field is 
ignored by NetUserAdd and NetUserSetInfo calls. 
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logon_hours points to a 21-byte (168 bits) map, each bit representing a unique 
hour in a week. The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59. Bit 1, word 
0 is Sunday, 1:00 to 1:59, and so on. If a bit is set in this bitmap, it means that 
logon is allowed. If a bit is cleared, it means logon is not allowed. 


Note: A NULL pointer permits access at all times. 


bad_pw_count is the number of attempts to validate a bad password. A value of 
-1 means unknown. This field is ignored by NetUserAdd and NetUserSetInfo 
calls. 


num_logons is the number of instances of logons to the account. A value of -1 
means unknown. This field is ignored by NetUserAdd and NetUserSetInfo 
calls. 


logon_server points to a NULL string. 


country_code is the OS/2 country code for the user’s language choice. This is 
used by the OS/2 LAN Requester/Server software to generate messages in the 
appropriate language whenever possible. 


code_page is the OS/2 code page for the language choice of the user. 


User Account Information (Level 10): The following structure is provided to allow 
users to retrieve limited information about themselves. 


struct user_info_10 { 


char usril10_name(UNLEN+1] ; 
char usril0_pad_1; 
char far * usril0_comment; 
char far * usril@_usr_comment; 
char far * usril0_full_name; 

}s 

where: 


usril0_name is the name of the user. 
usril0_pad_1l is for WORD-alignment of fields in the data structure. 


usril0_comment points to an ASCIIZ string which is for remarks or comments 
and can contain any type of text. The string can be NULL. 


usr_comment points to an ASCIIZ string which a user-settable field. The string 
can be NULL. 


usril0_full_name is the full name of user. 


~ 


User Account Information (Level 11): The following structure is provided to allow 
users to retrieve more information about other users. 
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struct user_info_11 { 


char usrill_name[UNLEN+1] ; 
char usrill_pad_1; 
char far * usril_comment; 
char far * usrill_usr_comment; 
char far * usrill_full_name; 
unsigned short usrill_priv; 
unsigned long usrill_auth_flags; 
long usrill_password_age; 
char far * usrill_home_dir; 
char far * usrill_parms; 
long usrill_last_logon; 
Tong usrill_last_logoff; 
long usrill_bad_pw_count; 
unsigned short usrill_num_logons; 
char far * usril1_logon_server; 
unsigned short usrill_country_code; 
char far * usrill_workstations; 
unsigned long usrill_max_storage; 
unsigned short usrill_units_per_week; 
unsigned char far * usrill_logon_hours; 
unsigned short usrill_code_page; 

}; 

where: 


usril 1_name is the name of the user. 
usrill_pad_1l is for WORD-alignment of fields in the data structure. 


usril1_comment is for remarks or comment; it can contain any type of text. The 
string can be NULL. 


usr_comment points to an ASCIIZ string which is a user-settable comment field. 
The string can be NULL. 


usrill_full_name points to an ASCIIZ string containing the full name of the 
user. The string can be NULL. 


usril1_priv is the user’s privilege level. It can be one of the following: 


Manifest Value Privilege 
USER_PRIV_GUEST 0 Guest 
USER_PRIV_USER 1 User 
USER_PRIV_ADMIN 2 Administrator 


usrill_auth_flags is reserved. 


usril1_password_age is the time (in seconds) since the password was last 
changed. 


usril 1_home_dir is the user’s home directory. It can be a null string. The 
absolute path can be local or UNC. 


usrill_parms points to an ASCIIZ string containing the name of the user’s home 
directory. The string can be NULL. 
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usrill_last_logon is the time and date (seconds since 1/1/70) when the last logon 
occurred. A value of zero means unknown. 


usrill_last_logoff is the time and date (seconds since 1/1/70) when the last logoff 
occurred. A value of zero means unknown. 


usrill_bad_pw_count is the number of attempts to validate a bad password. A 
value of -1 means unknown. 


usril 1_num_logons is the number of instances of logons to the account. A value 
of -1 means unknown. 


usril1_logon_server is the computer to handle logon requests for a user. 


usril1_country_code is the OS/2 country code for the user’s language choice. 
This is used by the OS/2 LAN Requester/Server software to generate messages in 
the appropriate language whenever possible. 


usril1_workstations is a list of requesters from which a user is permitted to log 
on. A NULL string means all requesters are allowed. (To disallow logon, the 
account disabled flag must be set.) Up to 8 requesters may be specified. The 
list of requesters can include IBM NETBIOS permanent names, which are listed 
as machine IDs, consisting of 12 hexidecimal digits. IBM NETBIOS permanent 
names are entered in the requester as shown as follows: 


16DF.Q2AC.7DE9 


usril 1_max_storage is a maximum storage allotted for the home directory. Units 
are K bytes. An entry of OXFFFFFFFF means that the account will never 
expire. 


usril1_units_per_week is the number of equal-length time units into which the 
week is divided. This value is used to compute the length of the bit string in 
logon_hours. It must be UNITS_PER_WEEK (168) for this release. 


usril1_logon_hours is a 21-byte (168 bits) map, each bit representing a unique 
hour in a week. The first bit (bit 0, word 0) is Sunday, 0:00 - 0:59. Bit 1, word 
0 is Sunday, 1:00 - 1:59, and so on. If a bit is set in this bitmap, it means that 
logon is allowed. If a bit is cleared, it means logon is not allowed. 


usrill_code_page is the OS/2 code page for the language choice of the user. 
Note: A NULL entry permits access at all times. 


User Modals Data Structure 
In order to control global modals, the following data structure is used. 


User Modals Information (Level 0) 


struct user_modals_info_0 


{ 


ie 


unsigned short usrmod0_min_passwd_len; 
unsigned long usrmod0_max_passwd_age; 
unsigned long usrmod0_min_passwd_age; 
unsigned long usrmod0_force_logoff; 
unsigned short usrmod0_password_hist_len; 
unsigned short usrmod0_max_reserved1 
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where: 


min_passwd_len is the minimum password length. The range of values is 0 to 
MAX _PASSWD_LEN. 


max_passwd_age is the maximum time (in seconds) since the password was last 
changed, and for which the current password is valid. A value of OxFFFFFFFF 
(TIMEQ FOREVER) allows the password to be valid forever. The minimum 
value is one day. 


min_passwd_age is the minimum time (in seconds) since the password was last 
changed, before which the current password is allowed to be changed. A value 
of 0 means there is no delay required between password updates. 


force_logoff is the length of time (in seconds) after the valid logon hours that the 
user should be forced off the network. The user will never be forced off if the 
value is TTIMEQ FOREVER (OxFFFFFFFF), or be forced off immediately if 
the value is 0. Any value between these can also be used. 


password_hist_len is the length of the password history, that is, the number of 
passwords in the history buffer that are scanned versus the new password in a 
NetUserPasswordSet attempt. The new password may not match any of the 
entries scanned. The history is of ENCRYPTED passwords. It can be 0 to 
DEF_MAX_PWHIST (currently 8). 


max_reserved! is not used. 


User Modals Information (Level 1) 


struct user_modals_info_l 


{ 
unsigned short usrmod1_role; 
char far * usrmod1_primary; 
}; 
where: 


role is the role of this database under a single system image (SSI). It can be one 
of the following: 


Manifest Value Meaning 
UAS_ROLE_STANDALONE 0 Standalone database 
UAS_ROLE_MEMBER 1 Member database in the domain 
UAS_ROLE_BACKUP 2 Backup database in the domain 
UAS_ROLE_PRIMARY 3 Primary database in the domain 


Without SSI, this field should always be set to STANDALONE. 


primary is the name of the primary domain to which this database belongs. It 
should match the primary domain name of the requester software on the local 
machine. 
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User Validation Data Structures 


User Validation Information (Requester) 


struct user_logon_req_1 { 


char usrreqi_name[UNLEN+1] ; 
char usrreql_pad_1; 
char usrreql_password[SESSION PWLEN] ; 
char far * usrreql_workstation; 
}3 
where: 


¢ usrreq]_name is the account name to which the user is attempting to log on. 


e usrreq]_pad is for WORD-alignment of data fields. 
e usrreql_password is the plain text ASCIIZ password. 


e usrreql]_workstation is the ASCIIZ string representing the requester from which 
the user is logging on. Can be NULL for local; ((long) -1) for unknown. 


User Validation Information (Level 0): The following is the logon data structure: 


struct user_logon_info_ 0 { 


char usrlog0_eff_name[UNLEN+1]; 
char usrlog0_pad_1; 

}3 

where: 


e usrlog0_eff_name is the name of the account to which the user was logged on. 


e usrlog0_pad is for WORD-alignment of the data structure. 


User Validation Information (Level 1) 


struct user_logon_info_1 { 
unsigned short usrlogl_code; 
char usrlogl_eff_name[UNLEN+1]; 
char usrlogi_pad_l; 
unsigned short usriogl priv; 
unsigned long usrlogl_auth_flags; 
unsigned short usrlogl_num_logons; 
unsigned short usrlogl_bad_pw_count; 
long usrlogl_last_logon; 
unsigned long usrlogl_last_logoff; 
unsigned long usriogl_logoff_time; 
unsigned long usrlogl_kickoff_time; 
long usrlogl_password_age; 
unsigned long usrlogl_pw_can_change; 
unsigned long usrlogl_pw_must_change; 

* 


char far usrlogl_computer; 
char far * usrlog1_domain; 
char far * usrlogl_script_path; 
unsigned long usrlogl_reserved1; 
}; 
where: 


Chapter 3. API Function Descriptions 


e usrlog1_code is the code explaining an action taken. The following are possible 


values: 

NERR_Success No problems were encountered. 

NERR_PasswordExpired The user has an account, but the user’s password 
has expired. No other conditions of logon have 
been checked. 


NERR_InvalidWorkstation The user was attempting to log on from an 
invalid requester. 
NERR_InvalidLogonHours The user was attempting to log on at an invalid 


time. 
ERROR_ACCESS DENIED Some condition of logon has not been met. 
NERR_StandaloneLogon No domain controller could be found to validate 


the user. Script processing was not performed. 
NERR_NonValidatedLogon The logon request was serviced by a 1.X logon 

server. Logon script processing was performed. 
NERR_LogonScriptError An error occurred processing logon script. 


The user_logon_info_1 data structure is returned by both the NetUserValidate2 
API and the NetWkstaSetUID2 API. The following codes may be returned by 
NetwkstaSetUID2, but are never returned by NetUserValidate2. 


NERR_StandaloneLogon No DC could be found to validate the user. 
NERR_LogonScriptError An error occurred processing the logon script. 


The other fields in the user_logon_info_] data structure are valid only when the 
API returns 0, and the code is VALIDATED_LOGON. 


e usrlogl_eff_name is the name of the account to which the user was logged on. 
¢ usrlog]_pad_1 is for WORD-alignment of data fields. 


e usrlog1_priv is the user’s privilege level. It can be one of the following: 


Manifest Value Privilege 
USER_PRIV_GUEST 0 Guest 
USER_PRIV_USER 1 User 
USER_PRIV_ADMIN Z Administrator 


e usrlog1_auth_flags is reserved. 


¢ usrlog]_num_logons is the number of instances of logons to the account. A value 
of -1 means unknown. 


¢ usrlogl_bad_pw_count is the number of attempts to validate a bad password. A 
value of -1 means unknown. 


e usrlogl_last_logon is the time and date (seconds since 1/1/70) when the last logon 
occurred. A value of zero means unknown. 


¢ usrlog1_last_logoff is the time and date (seconds since 1/1/70) when the last 
logoff occurred. A value of zero means unknown. 


e usrlog1_logoff_time is the time (in seconds) and date (since 1/1/70) when the user 
should log off. A value of ((long) -1) means never. 


¢ usrlog1_kickoff_time is the time (in seconds) when the system (server, 
communications manager, and so on.) should force the user to log off. This is 
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the sum of the logoff time and the grace period. A value of ((long) -1) means 


never. 


usrlog1_password_age is the time (in seconds) since the password was last 


changed. 


usrlog]_pw_can_change is the time (in seconds) and date (since 1/1/70) when the 
user can change his password. A value of -1 prevents users from changing their 


passwords. 


usrlog]1_pw_must_change is the time (in seconds) and the date (since 1/1/70) when 
the password must be changed. 


usrlog1_computer is the domain logged on by. It can be 0 for local. 


usrlog1_domain is the domain logged on by. It can be 0 for local. 


usrlog1_script_path is the relative path to the logon script of an account. 


usrlog1_reserved! is reserved for internal use only. Must be zero. 


User Validation Information (Level 2) 


st 


ruct user_logon_info 2 { 


char 

char 

char * 

char * 

char * 
unsigned long 


where: 


usrlog2_eff_name[UNLEN+1] ; 
usrlog2_pad_1; 
usrlog2_computer; 
usrlog2_fullname; 
usrlog2_usrcomment; 
usrlog2_logon_time; 


¢ usrlog2_eff_ name is the name of the account to which the user was logged on. 


usrlog2_pad_1 is for WORD-alignment of data fields. 


usrlog2_computer is the server logged on. Can be zero for local. 


usrlog2_fullname is the full name of the user. 


usrlog2_comment points to an ASCIIZ string which is a user-settable field for 
user comments. The string can be NULL. 


usrlog2_logon_time is the time and date (seconds since 1/1/70) when the user 
logged on. ((long) -1 means not available.) 


User Validation Information (Logoff): The following is the logoff data structure: 


struct user_logoff_info_1 { 

unsigned short usrlogl_code; 
unsigned long usrlogfl_duration; 
unsigned short usrlogfl_num_logons; 


ie 


where: 


¢ usrlogf1_code is dependent on the calling API. It is specified separately for each 


API. 


¢ usrlogf1_duration is the duration of a logon. Can be 0 for unknown. 
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¢ usrlogf1_num_logons is the number of logons by a user name. Can be -1 for 
unknown. 


Related Information 
For information on: 


e Logon scripts—See the IBM Operating System/2 Local Area Network Server 
Version 1.2 Network Administrator's Guide. 


e Share resource access permissions—See “Share Category” on page 3-337. 
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NetUserAdd 


Syntax 


Return Codes 


The NetUserAdd (admin, DOS) function establishes an account for a user in the use 
accounts subsystem (UAS) database and assigns a password and privilege level. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserAdd(servername, level, buf, buflen) 


char far * servername; 
short level; 
char far * buf; 


unsigned short buflen; 
where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ level specifies the level of detail (1 or 2) provided by the user_info_1 or 
user_info_2 data structures. 


¢ buf points to the user_info_1 or user_info_2 data structures. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_ SEEK 25 The seek is invalid. 
ERROR _NOT_SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 
NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_BadUsername 


NERR_ACFNotFound 
NERR_UserNotFound 
NERR_GroupExists 
NERR_UserExists 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFNoRoom 
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Value 
2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2202 


2219 


2221 


2223 


2224 


2226 


2227 


2228 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The user name or 
group name parameter 
is invalid. 

The Net.ACC file is 
missing. 

The user name cannot 
be found. 


The group name is 
already in use. 


The user account 
already exists. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


There are too many 
names in the access 
control file. 


Manifest Value Meaning 


NERR_ACFFileIOFail 2229 An error was 
encountered in 
accessing the accounts 


database. 
NERR_PasswordTooShort 2245 The password is 
shorter than required. 
NERR InvalidDatabase 2247 The UAS database file 
is corrupted. 
NERR_BadAsgType 2251 This asg_type is 
invalid. 
NERR_DevicelIsShared 2252 This device is already 
being shared. 
NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 
¢ DosChgFilePtr 
¢ DosDevIOCtlIOC_ENCRYPT) 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCtl(NETTRANSACTION) 
¢ DosFsCtlh(NIOC_ENCRYPT) 
¢ DosFsCthKNULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize [-ERROR_DISK_FULL] 
¢ DosQFileInfo 
¢ DosRead 
¢ DosSemClear 
¢ DosWrite. 

Remarks 
For add calls at level 1, the additional fields in the user_info_2 data structures are 


initialized to appropriate default values. These can be set to the desired values by 
subsequent NetUserSetInfo calls. The default values are as follows: 


usri2_full_name useri2_name 
usri2_usr_comment None (NULL string) 
usri2_parms None (NULL string) 
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usri2_workstations 
usri2_acct_expires 
usri2_max_storage 


usri2_logon_hours{] 


usri2_logon_server 
usri2_country_code 
usri2_code_page 


usri2_auth_flags 


All (NULL string) 
Never (OxFFFFFFFF) 
Unlimited (0XFFFFFFFF) 


Logon allowed anytime (each element OxFF; all bits set 
to 1) 


Domain controller (NULL string) 
Current country code on the server 
Current code page on the server 


None (0). 


The following fields must be set to 0: 


usri2_password_age 


reserved 


Related Information 


For information on: 


Set so that base time equals time of creation 
All reserved fields. 


e Listing user accounts on a server—See “NetUserEnum” on page 3-404. 


¢ Logon scripts—See the IBM Operating System/2 Local Area Network Server 
Version 1.2 Network Administrator's Guide. 


¢ Modifying a user account—See “NetUserSetInfo” on page 3-426. 


¢ Modifying a user’s group memberships—See “Group Category” on page 3-110. 


e Removing a user account—See “NetUserDel” on page 3-401. 
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NetUserDel 


Syntax 


Return Codes 


The NetUserDel (admin, DOS) function removes an account from the user account 
subsystem database, ending all access to the resources in the system. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 

NetUserDel (servername, username) 
char far * servername; 

char far * username; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ username points to an ASCIIZ string containing the user name to be deleted. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR NOT _SUPPORTED 50 This request is not 
supported by the 
network. 
ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 

NERR ShareMem 2104 An internal error 


occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 
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Manifest 
NERR_ServerNotStarted 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_UserNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_InvalidDatabase 
| NERR_InvalidComputer 
NERR_LastAdmin 


NERR_CanNotGrowUASFile 


3-402 LAN Server Application Programmer’s Reference 


Value 
2114 


2123 


2134 


2138 


2139 


2140 


2141 


2221 


2226 


2227 


2229 


2247 


2351 


2452 


2456 


Meaning 


The Server service has 
not been started. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The user name cannot 
be found. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


The last administrator 
cannot be deleted. 


It is not possible to 
grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosAllocSeg 

DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 
DosFsCth(NETTRANSACTION) 
DosFsCtl(NIOC_ENCRYPT) 
DosFsCtl(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosNewSize [-ERROR_DISK_FULL] 
DosQFileInfo 

DosRead 

DosSemClear 


DosWrite. 


Only a user or application with administrative privileges can delete another user’s 
account. 


Deleting an account also deletes all references to that account in all resource 
permission access records and from groups in the system. 


If the account being deleted is the last account in the database with administrative 
privilege, the error NERR_LastAdmin is returned and the delete function fails. 


Related Information 


For information on: 


Creating a user account of use of server resources—See “NetUserAdd” on 
page 3-397. 


Listing user accounts on a server—See “NetUserEnum” on page 3-404. 


Modifying a user account—See “NetUserSetInfo” on page 3-426. 
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-NetUserEnum 


Syntax 


Return Codes 


The NetUserEnum (partially admin, DOS) function returns information about all 
accounts on a server. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserEnum(servername, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
short levels; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


e level specifies the level of detail (0, 1, 2 or 10) returned in the user_info data 
structure. 


¢ buf points to the user_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_ DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_ MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_OS2loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR InternalError 


NERR_BadTransactConfig 


NERR_UserNotFound 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR _InvalidDatabase 


NERR _ BadAsgType 


Value 
2102 


2104 


2106 


2134 


2138 


2139 


2140 


2141 


2221 


2227 


2229 


2247 


2251 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The user name cannot 
be found. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The UAS database file 
is corrupted. 


This asg_type is 
invalid. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCthNETTRANSACTION) 
¢ DosFsCth(NULLTRANSACT) 
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¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosRead 


¢ DosSemClear. 


Remarks 
A user without administrative privileges can call this API with levels 0 or 10 only. 


NetUserEnum returns user_info_0, user_info_1, user_info_2, or user_info_10, 
components. If /evel is 1 or 2, the password component of each data structure will 
contain a string of spaces to maintain password security. 


Related Information 
For information on: 


e Listing all groups to which a user belongs—See “NetUserGetGroups” on 
page 3-407. 


e Retrieving the status of a particular user account—See “NetUserGetInfo” on 
page 3-410. 
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NetUserGetGroups 


Syntax 


Return Codes 


The NetUserGetGroups (partially admin, DOS) function lists the names of all 
groups in the user accounts subsystem (UAS) database to which a particular user 
belongs. Users can use the NetUserGetGroups function on their user names. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserGetGroups(servername, username, level, buf, buflen, 
entriesread, totalentries) 


char far * servername; 
char far * username; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * entriesread; 
unsigned short far * totalentries; 


where: 


© servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ username points to an ASCIIZ string indicating the name of the user to search 
for in each group account. 


e level specifies the level of detail (0) returned in the group_info_0 data structure 
(described below). 


¢ buf points to the group_info_0 data structure. 
e buflen specifies the size (in bytes) of the buf memory area. 


¢ entriesread points to an unsigned short integer indicating the number of entries 
that were returned to buf. 


¢ totalentries points to an unsigned short integer indicating the number of entries 
that were available. 


Group Membership (Level 0) 


struct group_info_0 { 
char grpi0_name[GNLEN+1]; 
}s 


where: 


¢ grpi0_name contains the names of the groups to which a user belongs. 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS DENIED 5 Administrative 


privilege is required. 
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Manifest 
ERROR_NOT_ENOUGH_MEMORY 


ERROR SEEK 
ERROR_INVALID PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE_DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_UserNotFound 


NERR_GroupExists 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR _ InvalidDatabase 
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Value 


pe) 
87 


124 


234 


2102 


2104 


2106 


2134 


2138 


2139 


2140 


2141 


2221 


2223 


2221 


2229 


2247 


Meaning 


Sufficient memory is 
not available. 


The seek is invalid. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The user name cannot 
be found. 


The group name is 
already in use. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The UAS database file 
is corrupted. 


Manifest Value Meaning 
NERR _InvalidComputer 2351 The specified computer 


name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosAllocSeg 

DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 

DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_ NOT_FOUND] 
DosNewSize [--ERROR_DISK_FULL] 
DosRead 


DosSemClear. 


NetUserGetGroups returns an array of group_info_0 data structures, indicating the 
names of all groups to which the user belongs. 


This is functionally equivalent to an Enum call because it enumerates the groups of 
which a user is a member. 


Related Information 


For information on: 


Retrieving the status of a user account—See “NetUserGetInfo” on page 3-410. 


Retrieving. and setting information about groups and their members on a 
server—See “Group Category” on page 3-110. 
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NetUserGetinfo 


The NetUserGetInfo (partially admin, DOS) function retrieves information about a 
particular account on a server. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserGetInfo(servername, username, level, 
buf, buflen, totalavail) 


char far * servername; 
char far * username; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 
where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ username points to an ASCIIZ string indicating the user’s account information 
to retrieve. 


¢ level specifies the level of detail (0, 1, 2, 10, 11) returned in the user_info data 
structure. 


¢ buf points to the user_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


° totalavail points to an unsigned short integer indicating the number of bytes of 
information that were available. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR_MORE_ DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
NERR_NetNotStarted 


NERR_ShareMem 


NERR_ RemoteOnly 


NERR_BufTooSmall 


NERR_OS82loctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_UserNotFound 
NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_InvalidDatabase 


NERR_InvalidComputer 


NERR_CanNotGrowVASFile 


Value 
2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2221 


Zell 


2229 


2247 


2351 


2456 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The user name cannot 
be found. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


It is not possible to 
grow the UAS file. 
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Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosAllocSeg 

DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 
DosFsCtlh(NETTRANSACTION) 
DosFsCtl(NULLTRANSACT). 
DosFsCtl(NetGetRdrAddr) . 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosNewSize [-ERROR_DISK_FULL] 
DosQFileInfo 

DosRead 

DosSemClear 


DosWrite. 


NetUserGetInfo can be used to retrieve information on the user’s privileges, home 
directory, and the status of an account. When /evel is 1 or 2, the password 
component of the user_info data structure contains a string of spaces to maintain 
password security. 


A user without administrative privileges can call this API with levels 0, 10, and 11 
only. Level 11 is available only for the account to which the user is logged on. 


Related Information 


For information on: 


Modifying a user’s account—See “NetUserSetInfo” on page 3-426. 


Retrieving a list of groups to which a user belongs—See “NetUserGetGroups” 
on page 3-407. 


Retrieving information on all user accounts on a server—See “NetUserEnum” on 
page 3-404. 
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NetUserModalsGet 
The NetUserModalsGet (DOS) function gets global modals-related information for 
all users and groups in the user accounts subsystem (UAS) database. 


Syntax 


Return Codes 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 


NetUserModalsGet( servername, level, buf, buflen, totalavail) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflen; 


unsigned short far * totalavail; 


where: 


¢ servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 


server. 


¢ level specifies the level of detail (0 or 1) supplied to the user_modals_info data 


structure. 


¢ buf points the user_modals_info data structure. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ totalavail points to the unsigned short integer indicating the number of bytes of 


information that were available. 


Manifest 
NERR_SUCCESS 


ERROR_ACCESS_DENIED 


ERROR_NOT_ENOUGH_MEMORY 


ERROR_INVALID PARAMETER 


ERROR_INVALID_LEVEL 


ERROR MORE DATA 


NERR_NetNotStarted 


Value 


87 


124 


234 


2102 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 
Sufficient memory is 
not available. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest Value Meaning 


NERR_ShareMem 2104 An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


NERR_RemoteOnly 2106 This operation is not 
supported on 
workstations. 

NERR_BufTooSmall 2123 The buffer is too small 
for fixed-length data. 

NERR_OSZ2IoctlError 2134 An internal error 


occurred when calling 
the workstation driver. 


NERR_WkstaNotStarted 2138 The Requester service 
has not been started. 
NERR _BrowserNotStarted 2139 The requested 
information is not 
available. 
NERR InternalError 2140 An internal error has 
occurred. 
NERR_BadTransactConfig 2141 The server is not 
configured for 
transactions. 
NERR_ACFNotFound 2219 The Net.ACC file is 
missing. 
NERR_UserNotFound 2221 The user name cannot 
be found. 
NERR_ACFNotLoaded 2227 The UAS database has 
not been started. 
NERR_ACFFileIOFail 2229 An error was 


encountered in 
accessing the accounts 
database. 


NERR_InvalidComputer 2351 The specified computer 
name is invalid. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosChgFilePtr 
¢ DosFsRamSemClear 
¢ DosFreeSeg 
¢ DosFsCth(NETTRANSACTION) 
¢ DosFsCtlh(NULLTRANSACT) 
¢ DosFsCtl(NetGetRdrAddr) 
¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
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¢ DosRead 


¢ DosSemClear. 
Remarks 
This function can be called even when the UAS system is not active, provided a 
valid UAS database exists. 


A user without administrative privileges can call this API with level 0 only. 
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NetUserModalsSet 
The NetUserModalsSet (admin, DOS) function sets global modals-related 
information for all users and groups in the user accounts subsystem (UAS) database. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserModalsSet( servername, level, buf, buflen, parmnum) 


char far * servername; 
short level; 
char far * buf; 
unsigned short buflens; 
short parmnum; 
where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ level specifies the level of detail (0 or 1) supplied to the user_modals_info data 
structure. 


¢ buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


e buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines which parameter to set. If parmnum is zero, level must be 0 
and buff must contain the user_modals_info_0 data structure. 


All fields in the user_modals_info_0 data structure, except accsys_status, are settable. 


Return Codes 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ACCESS_DENIED se] Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
NERR_NetNotStarted 


NERR _ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_ACFNotFound 
NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR InvalidComputer 


NERR_InvalidUASOp 


Value 
2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2219 


2227 


2229 


2351 


2451 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The Net.ACC file is 
missing. 

The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The specified computer 
name is invalid. 


This operation is not 
permitted when the 
Netlogon service is 
running. 
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Other error return codes may be returned from the following OS/2 functions: 


Remarks 


DosChgFilePtr 

DosFsRamSemClear 

DosFreeSeg 

DosFsCtlh(NETTRANSACTION) 
DosFsCtlh(NULLTRANSACT) 
DosFsCtl(NetGetRdrAddr) 
DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
DosRead 

DosSemClear 


DosWrite. 


This function can be called even when the UAS system is not active, provided a 
valid UAS database exists. SetInfo with level 1 can be called only when the 
accounts subsystem is inactive. 


The accounts system must be inactive in order to change the name of the database 
domain. 


NETLOGON cannot be running when setting the role field. 
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NetUserPasswordSet 


Syntax 


Return Codes 


The NetUserPasswordSet (DOS) function changes the password stored in a user’s 
account in the system. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 

NetUserPasswordSet(servername, username, oldpasswd, newpasswd) 
char far * servername; 

char far * username; 

char far * oldpasswd; 

char far * newpasswd; 


where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


* username points to an ASCIIZ string containing the name of the user whose 
password will be changed. 


¢ oldpasswd points to an ASCIIZ string specifying the user’s current password. 


¢ newpasswd points to an ASCIIZ string specifying a new password for the user. 


Manifest Value Meaning 

NERR_ SUCCESS 0 No errors were 
encountered. 

ERROR ACCESS DENIED 5 Administrative 
privilege is required. 

ERROR_NOT_ENOUGH_MEMORY 8 Sufficient memory is 
not available. 

ERROR SEEK 25 The seek is invalid. 

ERROR _INVALID_PASSWORD 86 The specified password 
is invalid. 

ERROR_INVALID_ PARAMETER 87 The specified 
parameter is invalid. 

ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 

ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 


NERR_NetNotStarted 2102 The redirector 
NETWKSTA.EXE has 
not been started. 
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Manifest 


Value 


Meaning 





NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IoctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_BadPassword 
NERR_UserNotFound 
NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_AccountExpired 
NERR_PasswordCantChange 
NERR_PasswordHistConflict 
NERR_PasswordTooShort 


NERR_PasswordTooRecent 
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2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2203 


2221 


2227 


2229 


2239 


2243 


2244 


2245 


2246 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The password 
parameter is invalid. 


The user name cannot 
be found. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The user account has 
expired. 


This password cannot 
change. 


This password cannot 
be used now. 


The password is 
shorter than required. 


The password is too 
recent to change. 


Remarks 


Manifest Value Meaning 


NERR _InvalidDatabase 2247 The UAS database file 
is corrupted. 


NERR _ InvalidComputer 2351 The specified computer 
name is invalid. 
NERR_CanNotGrowUASFile 2456 It is not possible to 


grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosDevIOCthIOC_ENCRYPT) 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCthNETTRANSACTION) 

¢ DosFsCthKNIOC_ENCRYPT) 

¢ DosFsCthNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE NOT_FOUND] 

¢ DosNewSize [-ERROR_DISK_FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 

¢ DosWrite 

¢ RdrDESEncrypt(NIOC_ENCRYPT) (pseudo FsCtl). 


Passwords are case-sensitive. 


The password will be set to newpasswd only if the oldpasswd matches the current 
password for the user and the newpasswd is not the same as the usrmodal10_phistien 
password. This call allows users to change their own password without 
administrative privilege. Password update restrictions apply. 


If users have administrative privilege and need to change a user’s password, without 
knowing their old password, they can use NetUserSetInfo instead. 


NetUserPasswordSet, if successful to the domain controller of a single system image 
(SSI) domain to which the user is currently logged on, also sets the current “default” 
password of the requester. This allows the user to connect to all servers in the 
domain, since the new password should rapidly replicate throughtout the domain. 
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Special Server Actions 


When used remotely, this API is handled in a special way. It must be allowed to 
succeed even when the user’s current password is expired. If the password of the 
account has expired but the account could otherwise log on, the server permits a 
NetUserPasswordSet to succeed. 


The server does this by examining the session setup, and if the session setup is 
followed by a PasswordSet transaction, the server will validate the session setup, 


process the transaction, and then close the session. 


Related Information 
For information on setting a password, see “NetUserSetInfo” on page 3-426. 
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NetUserSetGroups 


Syntax 


Return Codes 


The NetUserSetGroups (admin, DOS) function sets the groups of which a user is a 
member. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserSetGroups( servername, username, level, buf, buflen, entries) 


char far * servername; 
char far * username ; 
short level; 

char far * buf; 
unsigned short buflen; 
unsigned short entries; 
where: 


° servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ username points to an ASCIIZ string containing the name of the user whose 
group is being set. 


e level specifies the level of detail (0) supplied to the group_info_0 data structure. 
¢ buf points the group_info data structure. 
¢ buflen specifies the size (in bytes) of the buf memory area. 


¢ entries points to the unsigned short integer indicating the number of entries that 
were supplied in the buffer. 


Manifest Value Meaning 
NERR_SUCCESS 0 No errors were 
encountered. 
ERROR_ ACCESS DENIED 5 Administrative 
privilege is required. 
ERROR_NOT_ENOUGH_ MEMORY 8 Sufficient memory is 
not available. 
ERROR_SEEK 25 The seek is invalid. 
ERROR_INVALID_PARAMETER 87 The specified 
parameter is invalid. 
ERROR_INVALID_LEVEL 124 The Level parameter is 
invalid. 
ERROR MORE DATA 234 Additional data is 


available, but the 
buffer is too small. 
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Manifest 
NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OS2IloctlError 


NERR_WkstaNotStarted 


NERR_BrowserNotStarted 


NERR_InternalError 


NERR_BadTransactConfig 


NERR _InvalidAPI 


NERR_GroupNotFound 
NERR_UserNotFound 


NERR_NotPrimary 


NERR_ACFNotLoaded 


NERR_ACFFileIOFail 


NERR_SpeGroupOp 
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- Value 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2220 


2221 


2226 


2221 


2229 


2234 


Meaning 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too smail 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The group does not 
exist. 


The user name cannot 
be found. 


The UAS database is 
replicant and will not 
allow updates. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


This operation is not 
allowed on this special 
group. 


Manifest Value Meaning 


NERR _InvalidDatabase 2247 The UAS database file 
is corrupted. 

NERR_InvalidComputer 2351 The specified computer 
name is invalid. 

NERR_CanNotGrowUASFile 2456 It is not possible to 


grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCtlh(NETTRANSACTION) 

¢ DosFsCthNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize [-ERROR_DISK_FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 


¢ DosWrite. 
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NetUserSetinfo 
The NetUserSetInfo (partially admin, DOS) function modifies a user’s account in the 
system. 


Syntax 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 
NetUserSetInfo(servername, username, level, 
buf, buflen, parmnum) 


char far * servername; 
char far * username; 
short level; 
char far * buf; 
unsigned short buflen; 
short parmnum; 
where: 


® servername points to an ASCIIZ string containing the name of the remote server 
on which the function is to execute. A NULL pointer or string specifies a local 
server. 


¢ username points to an ASCIIZ string specifying which user’s account to modify. 
¢ level specifies the level of detail (1 or 2) provided by the user_info data structure. 


¢ buf points to the data structure if parmnum is zero. Otherwise, buf points to the 
specific data component that will be changed. 


Settable Fields Admin Owner 
name X 

password x 

priv x 

home_dir X 

comment X 

flags x 

script_path X 

auth_flags X 

full_name x 

usr_comment X x 
parms X X 
workstations X 

acct_expires X 

max_Storage X 

logon_hours x 

logon_server Xx 
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Return Codes 


Settable Fields Admin Owner 
country_code xX Xx 


code_page x x 


buflen specifies the size (in bytes) of the buf memory area. 


¢ parmnum determines whether buf contains a complete user_info data structure or 


a single component. If parmnum is 0, level can be 1 or 2, and buf must contain a 
complete user_info_I or user_info_2 data structure. Otherwise, parmnum must 
specify the ordinal position value for one of the following data structure 
components, as defined in ACCESS.H, as follows: 


Manifest Value Component 
PARMNUM_NAME 1 usrix_name 
PARMNUM_PASSWD 3 usrix_password 
PARMNUM_PRIV 5 usrix_priv 
PARMNUM DIR 6 usrix_home_dir 
PARMNUM_COMMENT 7 usrix_comment 
PARMNUM_USER_FLAGS 8 usrix_user_flags 
PARMNUM_SCRIPT_PATH 9 usrix_script_path 
PARMNUM_AUTH FLAGS 25 usri2_auth_flags 
PARMNUM_FULL_NAME 10 usri2_full_name 
PARMNUM_USR_COMMENT 11 usri2_usr_comment 
PARMNUM_PARMS 12 usri2_parms 
PARMNUM_WORKSTATIONS 13 usri2_workstations 
PARMNUM_ACCT_EXPIRES 16 usri2_acct_expires 
PARMNUM_MAX_ STORAGE 17 usri2_max_storage 
PARMNUM_UNITS_PER_WEEK 24 usri2_units_per_week 
PARMNUM_LOGON_HOURS 18 usri2_logon_hours 
PARMNUM_LOGON_SERVER 21 usri2_logon_server 
PARMNUM_COUNTRY_CODE 22 usri2_country_code 
PARMNUM_CODE PAGE 25 usri2_code_page 

Note: x = 1 or 2. 

Manifest Value Meaning 

NERR_ SUCCESS 0 No errors were 

encountered. 
ERROR ACCESS DENIED 5 Administrative 


privilege is required. 
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Manifest 
ERROR_NOT_ENOUGH_MEMORY 


ERROR_SEEK 
ERROR_NOT_SUPPORTED 


ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


ERROR_MORE_DATA 


NERR_NetNotStarted 


NERR_ShareMem 


NERR_RemoteOnly 


NERR_BufTooSmall 


NERR_OSZ2IoctlError 


NERR_WkstaNotStarted 


NERR _BrowserNotStarted 


NERR _InternalError 


NERR_BadTransactConfig 


NERR_InvalidAPI 


NERR_ACFNotFound 


NERR_UserNotFound 
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Value 


25 
50 


87 


124 


234 


2102 


2104 


2106 


2123 


2134 


2138 


2139 


2140 


2141 


2142 


2219 


2221 


Meaning 


Sufficient memory is 
not available. 


The seek is invalid. 


This request is not 
supported by the 
network. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 


The redirector 
NETWKSTA.EXE has 
not been started. 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


This operation is not 
supported on 
workstations. 


The buffer is too small 
for fixed-length data. 


An internal error 
occurred when calling 
the workstation driver. 


The Requester service 
has not been started. 


The requested 
information is not 
available. 


An internal error has 
occurred. 


The server is not 
configured for 
transactions. 


The requested API is 
not supported on the 
remote server. 


The Net.ACC file is 
missing. 


The user name cannot 
be found. 


Manifest Value Meaning 


NERR_NotPrimary 2226 The UAS database is 
replicant and will not 
allow updates. 


NERR_ACFNotLoaded 22a The UAS database has 
not been started. 
NERR_ACFFileIOFail 2229 An error was 


encountered in 
accessing the accounts 


database. 
NERR _PasswordTooShort 2245 The password is 
shorter than required. 
NERR_InvalidDatabase 2247 The UAS database file 
is corrupted. 
NERR_BadAsgType 2251 This asg_type is 
invalid. 
NERR_DevicelsShared 2252 This device is already 


being shared. 


NERR InvalidComputer 2351 The specified computer 
name is invalid. 


NERR_LastAdmin 2452 The last administrator 
cannot be deleted. 


Other error return codes may be returned from the following OS/2 functions: 
¢ DosAllocSeg 

¢ DosChgFilePtr 

* DosDevIOCtlhIOC_ENCRYPT) 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCtlh(NETTRANSACTION) 

¢ DosFsCri(NIOC_ENCRYPT) 

¢ DosFsCthKNULLTRANSACT) 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 

¢ DosNewSize [-ERROR_DISK_ FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 

¢ DosWrite 

¢ RdrDESEncrypt (NIOC_ENCRYPT) (pseudo FsCtl). 
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Remarks 
NetUserSetInfo can be called to change a user’s password only by users or 
applications having administrative privileges. Also note that the only restriction 
enforced when called by an administrator is that the new password length must be 
consistent with system modals. 


Note that all settable fields can be set by a user with administrative privilege. Any 
user may set the fields marked under “owner” for his own account. To do this, the 
user must use the parmnum option and cannot pass the whole structure. 
NULL_USERSETINFO_PASSWD must be used with parmnum 0 option if it is 
desired that the password not be changed. 


If this function is to change the privilege of or disable the last account in the 
database with administrative privilege, the error NERR_LastAdmin is returned and 
the function fails. 


Related Information 


For information on a particular user name on a server, see “NetUserGetInfo” on 
page 3-410. 
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NetUserValidate2 


Syntax 


Return Codes 


The NetUserValidate2 (local) function validates a user with its password. It checks 
if the user can log on based on logon restrictions defined for the account. 


#include <netcons.h> 
#include <access.h> 


unsigned far pascal 


NetUserValidate2( reservedi, level, buf, buflen, reserved2, totalavail ) 


char far reserved]; 
short level 

char far * buf 
unsigned short buflen; 
unsigned short reserved23 


unsigned short far * totalavail; 
where: 


e reserved] must be NULL. 


¢ level specifies the level of detail (1) supplied to the user_logon data structure. 


¢ buf points to the user_logon data structure. 


Buffer contents on call: A structure user_logon_req_1. The usrreq1_password is a 


plain text password. 


Buffer contents on response: A structure user_logon_info_1. 


¢ buflen specifies the size (in bytes) of the buf memory area. 


e reserved2 is reserved and must be zero. 


¢ totalavail points to the unsigned short integer indicating the number of bytes of 


information that were available. 


Manifest 
NERR_SUCCESS 


ERROR_ACCESS_ DENIED 


ERROR_SEEK 


ERROR_NOT_SUPPORTED 


ERROR_INVALID_PARAMETER 


ERROR_INVALID_LEVEL 


ERROR MORE DATA 


Value 


25 


50 


87 


124 


234 


Meaning 


No errors were 
encountered. 


Administrative 
privilege is required. 
The seek is invalid. 
This request is not 


supported by the 
network. 


The specified 
parameter is invalid. 


The Level parameter is 
invalid. 


Additional data is 
available, but the 
buffer is too small. 
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Manifest Value 
NERR_ShareMem 2104 
NERR_BrowserNotStarted 2139 
NERR_UserNotFound 2221 
NERR_GroupExists 2223 
NERR_ACFNotLoaded 2227 
NERR_ACFFileIOFail 2229 
NERR _InvalidDatabase 2247 
NERR_InvalidComputer 2351 
NERR_CanNotGrowUASFile 2456 


Meaning 


An internal error 
occurred—the network 
cannot access a shared 
memory segment. 


The requested 
information is not 
available. 


The user name cannot 
be found. 


The group name is 
already in use. 


The UAS database has 
not been started. 


An error was 
encountered in 
accessing the accounts 
database. 


The UAS database file 
is corrupted. 


The specified computer 
name is invalid. 


It is not possible to 
grow the UAS file. 


Other error return codes may be returned from the following OS/2 functions: 


¢ DosAllocSeg 

¢ DosChgFilePtr 

¢ DosFsRamSemClear 

¢ DosFreeSeg 

¢ DosFsCtl(NetGetRdrAddr) 

¢ DosGetShrSeg[-ERROR_FILE_NOT_FOUND] 
¢ DosNewSize [-ERROR_DISK_FULL] 

¢ DosQFileInfo 

¢ DosRead 

¢ DosSemClear 

¢ DosWrite 

e RdrDESEncrypt(NIOC_ENCRYPT) (pseudo FsCtl). 
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Remarks 


If the account named in usrreq1_name has no password, then any value in the 
password field will match. 


The behavior of this API is undefined if the value of reserved! is not zero. 


The code field in the user_logon_info_1 data structure can have the following error 
codes: 


Manifest Value Meaning 

NERR_SUCCESS 0 No errors were 
encountered. 

ERROR_ACCESS_DENIED 5 Administrative 
privilege is required. 

NERR_InvalidWorkstation 2240 The user is not allowed 
to log on from this 
requester. 

NERR_InvalidLogonHours 2241 The user is not allowed 
to log on at this time. 

NERR_PasswordExpired 2242 The password has 
expired. 


The rest of the user_info_1 structure is valid only when code is NERR_Success and 
the API returned either NERR_ Success orp ERROR _MORE_DATA. 


The bad password count field in the user’s record is incremented if the password 
failed to match. A successful match resets this field. 


The behavior of this API is undefined if the value of reserved! is not zero. 
This function works on the local system only. If there is a standalone UAS database 


(NET.ACC) existing on the requester, this API, when executed, will validate against 
the local UAS database instead of the UAS database of the domain. 
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Appendix A. Include Files 


This appendix lists and describes each of the include files provided with the OS/2 
LAN Requester/Server applications program interface (API). The include files 
declare information such as constants, storage classes, and function parameter types 
that the OS/2 LAN Requester/Server API functions require. Each include file 
declares information pertinent to a particular category of functions described in 
Chapter 3, “API Function Descriptions.” All OS/2 LAN Requester/Server include 
files are stored in the \IBMLAN\NETSRC\H directory. 


The API functions use the include files listed as follows: 


API Category Include Files Meaning 


All OS82.H Declares structures, 
constants, and functions in 
the base operating system. 


Note: The OS/2.H include 
file is not part of the 
OS/2 LAN 
Requester/Server 
include files. 


NETCONS.H Declares constants used with 
various components of OS/2 
LAN Requester/Server. 
Used with all OS/2 LAN 
Requester/Server functions. 


NETERR.H Declares error manifests for 
LAN Server return codes. 
Used with all OS/2 LAN 
Requester/Server functions. 


Access Permission ACCESS.H Declares structures, 
constants, and functions that 
extract information and 
control the access privileges 
for the shared resources of a 
server. Used with functions 
in the Access Permissions, 
Groups, and User categories. 


Alert ALERT.H Declares message constants 
used by the alerter service 
program in conjunction with 
functions in the Alert 
category. 


ALERTMSG.H Declares structures, 
constants, or functions that 
wait for specific events to 
occur, enabling the operation 
of several network services. 
Used with functions in the 
Alert category. 
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API Category 
Audit 


Configuration 


Connection 


Domain 


Error Logging 


File 


Handle 


Include Files 
AUDIT.H 


CONFIG.H 


SHARES.H 


ACCESS.H 


ERRLOG.H 


SHARES.H 


CHARDEV.H 
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Meaning 


Declares structures and 
constants used for adding 
events to the audit log of a 
requester or server. Used 
with functions in the 
Auditing category. 


Declares functions that 
retrieve the parameter of a 
particular component from 
the IBMLAN.INI file. Used 
with functions in the 
Configuration category. 


Declares structures, 
constants, and functions that 
list information about the 
resources a server is sharing. 
Used with functions in the 
Connection, File, Session, 
and Share categories. 


Declares structures, 
constants, and functions that 
extract information and 
control the access privileges 
for the shared resources of a 
server. Used with functions 
in the Access Permissions, 
Groups, and User categories. 


Declares structures and 
functions that clear, close, 
log on to, open, or read the 
error log file. Also declares 
the constants that define the 
error codes related to the 
operating system or 
redirector. Used with 
functions in the Error 
Logging category. 


Declares structures, 
constants, and functions that 
list information about the 
resources a server is sharing. 
Used with functions in the 
Connection, File, Session, 
and Share categories. 


Declares structures, 
constants, and functions used 
to modify, list, retrieve, and 
delete shared serial devices 
and queues. Used with 
functions in the Serial Device 
category. 


API Category 
Group 


Mailslot 


Message 


Remote Utility 


Requester 


Serial Device 


Include Files 
ACCESS.H 


MAILSLOT.H 


MESSAGE.H 


REMUTIL.H 


WKSTA.H 


ACCESS.H 


CHARDEV.H 


Meaning 


Declares structures, 
constants, and functions that 
extract information and 
control the access privileges 
for the shared resources of a 
server. Used with functions 
in the Access Permissions, 
Groups, and User categories. 


Declares functions that 
create, delete, read, and write 
mailslots on a server. Used 
with functions in the 
Mailslot category. 


Declares structures, 
constants, and functions that 
send one-way messages, read 
messages, or log messages. 
Used with functions in the 
Message category. 


Declares data structures, 
constants, and functions used 
by remote utilities. Used 
with functions in the Remote 
Utility category. 


Declares structures, 
constants, and functions that 
control the working 
environment of a requester. 
Used with functions in the 
Requester category. 


Declares structures, 
constants, and functions that 
extract information and 
control the access privileges 
for the shared resources of a 
server. Used with functions 
in the Access Permissions, 
Groups, and User categories. 


Declares structures, 
constants, and functions used 
to modify, list, retrieve, and 
delete shared serial devices 
and queues. Used with 
functions in the Serial Device 
category. 
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API Category 


Server 


Service 


Session 


Share 


Spooler 


Statistics 


Use 


Include Files 


SERVER.H 


SERVICE.H 


SHARES.H 


SHARES.H 


PMSPL.H 


NETSTATS.H 


ACCESS.H 
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Meaning 


Declares structures, 
constants, and functions that 
retrieve or set information 
regarding a server. Used 
with functions in the Server 
category. 


Declares structures, 
constants, and functions that 
install or control network 
service programs on a server. 
Used with functions in the 
Service category. 


Declares structures, 
constants, and functions that 
list information about the 
resources a server is sharing. 
Used with functions in the 
Connection, File, Session, 
and Share categories. 


Declares structures, 
constants, and functions that 
list information about the 
resources a server is sharing. 
Used with functions in the 
Connection, File, Session, 
and Share categories. 


Part of the OS/2 
Presentation Manager™ 
include files which declare 
structures, constants, and 
functions used to print in 
PM Spooler. 


Declares structures, 
constants, and functions that 
clear or retrieve statistical 
information about the 
performance of a server. 
Used with functions in the 
Statistics category. 


Declares structures, 
constants, and functions that 
extract information and 
control the access privileges 
for the shared resources of a 
server. Used with functions 
in the Access Permission, 
Group, and User categories. 


API Category Include Files Meaning 


User USER.H Declares structures, 
constants, and functions that 
retrieve or control user 
information. Used with 
functions in the User 
category. 


Presentation Manager is a trademark of International Business Machines Corporation. 
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Appendix B. Function Libraries 


This appendix describes the different libraries that a program can be linked to when 
calling a OS/2 LAN Requester/Server function. Programs link to standard libraries 
(.LIB) and dynamically linked libraries (DLL). Standard libraries provide 

information such as the name of a dynamically linked run-time library to the 
relocatable object code at link time. Dynamically linked libraries contain the actual 
assembler code of a function and are executed at run time. In addition, this 
appendix provides an alphabetical list of all OS/2 LAN Requester/Server functions 


with each required library, other software required to execute each function, and 


special notes. 


Note: The function names are spelled in the uppercase and lowercase style required 


for C language programs. 


Link-Time Libraries 


At link time, any program that calls a particular API function must be linked to a 
library (.LIB) containing information about the function. Link-time libraries 
provide information that allows the operating system to dynamically link the 
appropriate dynamically linked library to a program at run time. 
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Any program calling any of the following functions must be linked to the 


NETAPI.LIB library: 


NetAccessAdd 
NetAccessCheck 
NetAccessDel 
NetAccessEnum 
NetAccessGet Info 
NetAccessGetUserPerms 
NetAccessSet Info 
NetAlertRaise 
NetAlertStart 
NetAlertStop 
NetAuditClear 
NetAuditRead 
NetAuditWrite 
NetCharDevControl 
NetCharDevEnum 
NetCharDevGet Info 
NetCharDevQEnum 
NetCharDevQGet Info 
NetCharDevQPurge 
NetCharDevQPurgeSel f 
NetCharDevQSetInfo 
NetConfigGet2 
NetConfigGetAl112 
NetConnectionEnum 
NetErrorLogClear 
NetErrorLogRead 
NetErrorLogWrite 
NetFileClose2 
NetFileEnum2 
NetFileGetInfo2 
NetGetDCName 
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NetGroupAdd 
NetGroupAddUser 
NetGroupDel 
NetGroupDelUser 
NetGroupEnum 
NetGroupGet Info 
NetGroupGetUsers 
NetGroupSetInfo 
NetGroupSetUsers 
NetLogonEnum 
NetHandleGet Info 
NetHandleSetInfo 
NetMessageLogFileGet 
NetMessageLogFileSet 
NetMessageNameAdd 
NetMessageNameDel 
NetMessageNameEnum 
NetMessageNameFwd 
NetMessageNameGet Info 
NetMessageNameUnFwd 
NetRemoteCopy 
NetRemoteExec 
NetRemoteMove 
NetRemoteT0D 
NetServerAdminCommand 
NetServerDiskEnum 
NetServerGetInfo 
NetServerSet Info 
NetServiceControl 
NetServiceEnum 
NetServiceGet Info 
NetServiceInstal] 
NetServiceStatus 
NetSessionDel 
NetSessionEnum 
NetSessionGetInfo 
NetShareAdd 
NetShareCheck 
NetShareDel 
NetShareEnum 
NetShareGet Info 
NetShareSetInfo 
NetStatisticsGet2 
NetUseAdd 
NetUseDel 
NetUseEnum 
NetUseGetInfo 
NetUserAdd 
NetUserDel 
NetUserEnum 
NetUserGetGroups 
NetUserGetInfo 
NetUserModalsGet 
NetUserModalsSet 
NetUserPasswordSet 
NetUserSetGroups 
NetUserSetInfo 
NetUserVal idate2 
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NetWkstaGetInfo 
NetWkstaSetInfo 
NetWkstaSetUID2 


Any program calling any of the following functions must be linked to the 


NETOEM.LIB library: 
NetMessageBuf ferSend 


NetMessageFileSend 
NetServerEnum2 


Any program calling any of the following functions must be linked to the OS2.LIB 


library: 


DosBufReset 

DosCal 1NmPipe 
DosClose 
DosConnectNmPipe 
DosDisconnectNmPipe 
DosMakeNmPipe 
DosOpen 
DosPeekNmPi pe 
DosQNmPipeInfo 
DosQNmPipeSemState 
DosQNmPHandState 
DosRead 
DosReadAsync 
DosSetNmPipeSem 
DosSetNmPHandState 
DosTransactNmPipe 
DosWaitNmPipe 
DosWrite 
DosWriteAsync 
Sp1QmAbort 
Sp1QmClose 
Sp1QmEndDoc 
Sp1Qm0pen 
Sp1QmStartDoc 
Sp1QmWrite 


Any program calling any of the following functions must be linked to the 


MAILSLOT.LIB library: 


DosDeleteMailslot 
DosMailslotinfo 
DosMakeMailslot 
DosPeekMai1slot 
DosReadMailslot 
DosWriteMailslot 
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Run-Time Libraries 


At run time, any program that calls a particular API function must be dynamically 
linked to a library containing the executable binaries for that function. The OS/2 
operating system automatically links the program and library together when a 
particular function is called. 


OS/2 LAN Requester/Server provides the following dynamically linked libraries: 


Library Contents 

MAILSLOT.DLL Mailslot API library. 

NETAPI.DLL Base network API library. 

NETOEM.DLL Reserved. 

SPLIA.DLL OS/2 LAN Requester/Server extension of the 


Presentation Manager spooler library. 


Function Notes 


This section provides an alphabetical list of each OS/2 LAN Requester/Server API 
function, and other software required at run time. 


The following list denotes special requirements for each OS/2 LAN Requester/Server 
API function: 


Requires requester service 

Requires messenger service 

Requires server service 

Can be remotely executed 

Requires administrative privileges (remote only) 
Has a local-only library available. 


rp rng s 


The following table lists each OS/2 LAN Requester/Server API function and its 
associated requirements. 


API Name Requirements (W M S R A L) 
DosBufReset WL 
DosCaliNmPipe WL 
DosClose WL 
DosConnectNmPipe WL 
DosDeleteMailslot WL 
DosDisconnectNmPipe WL 
DosDupHandle WL 
DosMailslotInfo WL 
DosMakeMailslot WL 
DosMakeNmPipe WL 
DosOpen WL 
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API Name 
DosPeekMailslot 
DosPeekNmPipe 
DosQFHandState 
DosQHandType 
DosQNmPHandState 
DosQNmPipelnfo 
DosQNmPipeSemState 
DosRead 
DosReadAsync 
DosReadMailslot 
DosSetFHandState 
DosSetNmpHandState 
DosSetNmPipeSem 
DosTransactNmPipe 
DosWaitNmPipe 
DosWrite 
DosWriteAsync 
DosWriteMailslot 
NetAccessAdd 
NetAccessCheck 
NetAccessDel 
NetAccessEnum 
NetAccessGetInfo 
NetAccessGetUserPerms 
NetAccessSetInfo 
NetAlertRaise 
NetAlertStart 
NetAlertStop 
NetAuditClear 
NetAuditRead 
NetAuditWrite 
NetCharDevControl 
NetCharDevEnum 
NetCharDevGetInfo 
NetCharDevQEnum 
NetCharDevQGetInfo 


Requirements (W MS RAL) 


WL 


WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WL 
WRA 
WR 
WRA 
WRA 
WRA 
WRA 
WSRA 
WwW 

WwW 

WwW 
WRA 
WRA 
Ws 
WSRA 
WSR 
WSR 
WSR 
WSR 
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API Name 
NetCharDevQPurge 
NetCharDevQPurgeSelf 
NetCharDevQSetInfo 
NetConfigGet2 
NetConfigGetAll2 
NetConnectionEnum 
NetErrorLogClear 
NetErrorLogRead 
NetErrorLogWrite 
NetFileClose2 
NetFileEnum2 
NetFileGetInfo2 
NetGetDCName 
NetGroupAdd 
NetGroupAddUser 
NetGroupDel 
NetGroupDel User 
NetGroupEnum 
NetGroupGetInfo 
NetGroupGetUsers 
NetGroupSetInfo 
NetGroupSet Users 
NetHandleGetInfo 
NetHandleSetInfo 
NetLogonEnum 
NetMessageBufferSend 
NetMessageFileSend 
NetMessageLogFileGet 
NetMessageLogFileSet 
NetMessageNameAdd 
NetMessageNameDel 
NetMessageNameEnum 
NetMessageNameFwd 
NetMessageNameGetInfo 
NetMessageNameUnFwd 
NetRemoteCopy 
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Requirements (W MS R A L) 


WSRA 
WSR 
WSRA 
WRA 
WRA 
WSRA 
WRA 
WRA 
Ws 
WSRA 
WSRA 
WSRA 
WR 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRS 
WRS 
WR 
WRA 
WRA 
WMRA 
WMRA 
WMRA 
WMRA 
WMRA 
WMRA 
WMRA 
WMRA 
WR 


API Name 
NetRemoteExec 
NetRemoteMove 
NetRemoteTOD 
NetServerAdminCommand 
NetServerDiskEnum 
NetServerEnum2 
NetServerGetInfo 
NetServerSetInfo 
NetServiceControl 
NetServiceEnum 
NetServiceGetInfo 
NetServiceInstall 
NetServiceStatus 
NetSessionDel 
NetSessionEnum 
NetSessionGetInfo 
NetShareAdd 
NetShareCheck 
NetShareDel 
NetShareEnum 
NetShareGetInfo 
NetShareSetIinfo 
NetStatisticsGet2 
NetUseAdd 
NetUseDel 
NetUseEnum 
NetUseGetInfo 
NetUserAdd 
NetUserDel 
NetUserEnum 
NetUserGetGroups 
NetUserGetInfo 
NetUserModalsGet 
NetUserModalsSet 
NetUserPasswordSet 
NetUserSetGroups 


Requirements (W MS R A L) 


WR 
WR 
WR 
WSRA 
WRA 
WR 
WSRA 
WSRA 
WRA 
WR 
WR 
WRA 
WwW 
WSRA 
WSRA 
WSRA 
WSRA 
WSR 
WSRA 
WSR 
WSR 
WSRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WRA 
WSRA 
WRA 
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API Name Requirements (W MS RAL) 


NetUserSetInfo WRA 
NetUserValidate2 WwW 
NetWkstaGetInfo WRA 
NetWkstaSetInfo WRA 
NetWkstaSetUID2 WwW 
SplQmA bort R 
SplQmClose R 
SplQmEndDoc R 
SplQmOpen R 
SplQmStartDoc R 
SplQmWrite R 
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Appendix C. Return Codes 


This appendix lists the identifiers and return codes for the OS/2 LAN 
Requester/Server API functions defined in the NETERR.H include file. 


For a function-by-function listing of return codes, see Chapter 3, “API Function 
Descriptions.” 


Successful Return Codes 


Redirector 


© Copyright IBM Corp. 1990 


An OS/2 LAN Requester/Server API function that encounters no error returns the 
following code. 


0 No errors were encountered. 


Originator: NERR_ SUCCESS 


An OS/2 LAN Requester/Server API function returning error codes 51 to 79 or 230 
to 249 encountered an error with the redirector. 


51 This remote computer is not listening. 


Originator: ERROR_REM_NOT LIST 


52 A duplicate name exists on the network. 


Originator: ERROR_DUP_NAME 


53 The network path cannot be found. 
Originator: ERROR _BAD NETPATH 


54 The network is busy. 
Originator: ERROR _NETWORK_ BUSY 


55 This device does not exist on the network. 


Originator: ERROR _DEV_NOT_EXIST 


56 The IBM NETBIOS command limit has been exceeded. 
Originator: ERROR_TOO_MANY_ CMDS 
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57 A network adapter hardware error has occurred. 


Originator: ERROR_ADAP HDW_ERR 


58 The network has responded incorrectly. 
Originator: ERROR _BAD_NET_RESP 


59 An unexpected network error has occurred. 


Originator: ERROR _UNEXP_NET_ERR 


60 The remote adapter being used is incompatible. 
Originator: ERROR _BAD_REM_ADAP 


61 The print queue is full. 
Originator: ERROR_PRINTQ FULL 


62 There is not enough memory available for the requested print file. 


Originator: ERROR_NO SPOOL SPACE 


63 The requested print file has been canceled. 
Originator: ERROR _PRINT_CANCELLED 


64 The network name was deleted. 
Originator: ERROR _NETNAME DELETED 


65 Network access is denied. 
Originator: ERROR_NETWORK ACCESS DENIED 


66 This network device type is incorrect. 
Originator: ERROR_BAD_DEV_TYPE 


67 This network name cannot be found. 


Originator: ERROR_BAD_NET NAME 


68 The network name limit has been exceeded. 
Originator: ERROR_TOO_MANY_NAMES 


C-2 LAN Server Application Programmer’s Reference 


€9 The IBM NETBIOS session limit has been exceeded. 
Originator: ERROR _TOO_MANY_SESS 


70 File sharing has been temporarily paused. 
Originator: ERROR SHARING PAUSED 


71 This request is not accepted by the network. 
Originator: ERROR REQ NOT_ACCEP 


72 Print or disk redirection is temporarily paused. 
Originator: ERROR_REDIR_ PAUSED 


230 This is a non-existent pipe or an invalid operation 


Originator: ERROR _BAD_ PIPE 


231 The specified pipe is busy. 
Originator: ERROR_PIPE BUSY 


232 There is no data on a non-blocking read. 


Originator: ERROR_NO_DATA 


233 The pipe was disconnected by the server. 
Originator; ERROR PIPE NOT_CONNECTED 


234 Additional data is available, but the buffer is too small. 
Originator: ERROR MORE DATA 


240 The session was canceled. 


Originator: ERROR_VC_DISCONNECTED 


Network Utilities 


An OS/2 LAN Requester/Server API function returning error codes 2100 to 2140 
encountered an error with a network utility. 


2102 The redirector NETWKSTA.EXE has not been started. 
Originator; NERR_NetNotStarted 
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2103 The server cannot be located. 


Originator: NERR_UnknownServer 


2104 An internal error occurred—the network cannot access a shared memory 
segment. 


Originator: NERR_ShareMem 


2105 A network resource shortage occurred. 


Originator: NERR_NoNetworkResource 


2106 This operation is not supported on workstations. 
Originator: NERR_RemoteOnly 


2107 The device is not connected. 


Originator: NERR_DevNotRedirected 


2108 Unknown local device. 
Originator: NERR_UnknownLocalDev 


2114 The Server service has not been started. 


Originator: NERR_ServerNotStarted 


2115 The device queue is empty. 
Originator: NERR_ItemNotFound 


2116 The device or directory does not exist. 


Originator: NERR_UnknownDevDir 


2117 The operation is invalid on a redirected device. 


Originator: NERR_RedirectedPath 


2118 The name has already been shared. 
Originator: NERR_DuplicateShare 


2119 The server is currently out of the requested resource. 


Originator: NERR_NoRoom 
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Spooler 


2121 The requested add of item exceeds maximum allowed. 


Originator: NERR_TooManyltems 


2123 The buffer is too small for fixed-length data. 
Originator: NERR_BuffooSmall 


2127 A remote API error has occurred. 


Originator; NERR_ RemoteErr 


2131 An error occurred when opening or reading the IBMLAN.INI file. 
Originator: NERR_LanIniError 


2134 An internal error occurred when calling the workstation driver. 


Originator: NERR_OS2IoctlError 


2136 A general network error has occurred. 


Originator: NERR_NetworkError 


2138 The Requester service has not been started. 


Originator: NERR_WkstaNotStarted 


2139 The requested information is not available. 


Originator: NERR_BrowserNotStarted 


2140 An internal error has occurred. 


Originator: NERR_InternalError 


An OS/2 LAN Requester/Server API function returning error codes 2150 to 2179 
encountered an error while modifying a network spooler. 


2150 The printer queue does not exist. 


Originator; NERR_ QNotFound 


2151 The print job does not exist. 
Originator: NERR_ JobNotFound 
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2152 


Originator: 


2154 


Originator: 


2155 


Originator: 


2156 


Originator: 


2157 


Originator: 


2158 


Originator: 


2159 


Originator: 


2160 


Originator: 


2161 


Originator: 


2163 


Originator: 


2164 


Originator: 


2165 


Originator: 


The printer destination cannot be found. 


NERR_DestNotFound 


The printer queue already exists. 


NERR_QExists 


No more printer queues can be added. 


NERR_QNoRoom 


No more print jobs can be added. 


NERR_JobNoRoom 


No more printer destinations can be added. 


NERR_DestNoRoom 


This printer destination is idle and cannot accept control operations. 


NERR _Destldle 


This printer destination request contains an invalid control function. 


NERR_DestInvalidOp 


The printer processor is not responding. 


NERR_ProcNoRespond 


The spooler service has not been started. 


NERR_SpoolerNotLoaded 


This operation cannot be performed on the printer queue in its current 
State. 


NERR_QlInvalidState 


This operation cannot be performed on the print job in its current state. 


NERR_JobInvalidState 


A spooler memory allocation failure has occurred. 


NERR_SpoolNoMemory 
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Service 


An OS/2 LAN Requester/Server API function returning error codes 2180 to 2199 
encountered an error with one of the network services. 


2180 The service does not respond to control actions. 


Originator: NERR_ServiceTableLocked 


2181 The service table is full. 
Originator: NERR_ServiceTableFull 


2182 The requested service has already been started. 
Originator: NERR ServiceInstalled 


2183 The service does not respond to control actions. 


Originator: NERR_ServiceEntryLocked 


2184 The service has not been started. 


Originator: NERR_ServiceNotInstalled 


2185 The service name is invalid. 


Originator: NERR_BadServiceName 


2186 The service is not responding to the control function. 


Originator: NERR_ServiceCtlTimeout 


2187 The service control is busy. 
Originator: NERR_ServiceCtlBusy 


2188 The IBMLAN.INI file contains an invalid service program name. 
Originator: NERR_BadServiceProgName 


2189 The service cannot be controlled in its present state. 


Originator: NERR_ServiceNotCtrl 


2190 The service was ended abnormally. 


Originator; NERR _ ServiceKillProc 
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2191 The requested pause or stop is not valid for this service. 


Originator: NERR_ServiceCtlNotValid 


Requester 


An OS/2 LAN Requester/Server API function returning error codes 2200 to 2219 
encountered an error with a requester. 


2200 This workstation is already logged on. 
Originator: NERR_AlreadyLoggedOn 


2201 This workstation has not been logged on yet. 
Originator: NERR_NotLoggedOn 


2202 The user name or group name parameter is invalid. 


Originator: NERR_BadUsername 


2203 The password parameter is invalid. 


Originator: NERR_BadPassword 


2204 The logon processor did not add the message alias. 
Originator; NERR_UnableToAddName_W 


2205 The logon processor did not add the message alias. 
Originator: NERR_UnableToAddName_F 


2206 The logoff processor did not delete the message alias. 
Originator: NERR_UnableToDelName_W 


2207 The logoff processor did not delete the message alias. 
Originator: NERR_UnableToDelName_F 


2210 A centralized logon server conflict has occurred. 


Originator: NERR_LogonServerConflict 


2211 The server is configured without a valid user path. 


Originator; NERR_LogonNoUserPath 
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2212 -An error occurred while loading or running the logon script. 


Originator: NERR_LogonScriptError 


2213 Unable to use resources. 


Originator: NERR_CentralLogonFailed 


2214 The logon server was not specified—standalone logon will occur. 


Originator: NERR_StandaloneLogon 


2215 The logon server cannot be found. 


Originator: NERR_LogonServerNotFound 


2216 There is already a logon domain for this computer. 


Originator: NERR_ LogonDomainExists 


2217 The logon server could not validate the logon. 
Originator: NERR_NonValidatedLogon 


Access, User, and Group 


An OS/2 LAN Requester/Server API function returning error codes 2220 to 2249 
encountered an error while requesting or modifying information concerning network 
privileges. 


2220 The group does not exist. 
Originator: NERR_GroupNotFound 


2221 The user name cannot be found. 


Originator: NERR_UserNotFound 


2222 The netname cannot be found. 


Originator: NERR_ResourceNotFound 


2223 The group name is already in use. 


Originator: NERR_ GroupExists 


2224 The user account already exists. 


Originator; NERR_UserExists 
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2225 The resource permission list already exists. 


Originator: NERR_ResourceExists 


2226 The UAS database is replicant and will not allow updates. 
Originator: NERR_NotPrimary 


2227 The UAS database has not been started. 
Originator: NERR_ACFNotLoaded 


2228 There are too many names in the access control file. 


Originator: NERR_ACFNoRoom 


2229 An error was encountered in accessing the accounts database. 


Originator: NERR_ACFFileIOFail 


2230 Too many lists were specified. 
Originator: NERR_ACFTooManyLists 


2231 Deleting a user with a session is not allowed. 


Originator: NERR_UserLogon 


2232 The parent directory cannot be located. 
Originator: NERR_ACFNoParent 


2233 Unable to grow UAS sess cache segment. 
Originator: NERR_CanNotGrowSegment 


2234 This operation is not allowed on this special group. 
Originator: NERR_SpeGroupOp 


2235 This user is not cached in UAS sess cache. 
Originator; NERR_NotInCache 


2236 The user already belongs to this group. 
Originator: NERR_UserInGroup 
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2237 The user does not belong to this group. 
Originator: NERR_UserNotInGroup 


2238 The user account is undefined. 


Originator: NERR_AccountUndefined 


2239 The user account has expired. 


Originator; NERR_AccountExpired 


2240 The user is not allowed to log on from this requester. 
Originator: NERR_InvalidWorkstation 


2241 The user is not allowed to log on at this time. 
Originator: NERR_ InvalidLogonHours 


2242 The password has expired. 
Originator: NERR_PasswordExpired 


2243 This password cannot change. 
Originator: NERR_ PasswordCantChange 


2244 This password cannot be used now. 


Originator: NERR_PasswordHistConflict 


2245 The password is shorter than required. 
Originator: NERR_PasswordTooShort 


2246 The password is too recent to change. 


Originator: NERR_PasswordTooRecent 


2247 The UAS database file is corrupted. 
Originator: NERR_InvalidDatabase 


2248 No updates are neccessary to this replicant. 
Originator: NERR_Data2249UpToDate 
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Use 


An OS/2 LAN Requester/Server API function returning error codes 2250 to 2269 
encountered an error while trying to retrieve information about a resource or while 
using a resource. 


2250 The connection cannot be found. 


Originator: NERR_UseNotFound 


2251 This asg_type is invalid. 
Originator: NERR_BadAsgType 


2252 This device is already being shared. 
Originator; NERR_DevicelsShared 


Message 


An OS/2 LAN Requester/Server API function returning error codes 2270 to 2309 
encountered an error while processing information about a server. 


2270 A computer name has not been configured. 


Originator: NERR_NoComputerName 


2271 This message server has already been started. 


Originator; NERR_MsgAlreadyStarted 


2272 The message server initialization request has failed. 


Originator: NERR_MsglInitFailed 


2273 The message alias cannot be found on the local area network. 


Originator: NERR_NameNotFound 


2274 This message alias has already been forwarded. 


Originator: NERR_AlreadyForwarded 


2275 This message alias has been added but is still forwarded. 
Originator: NERR_AddForwarded 
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2276 


Originator: 


2277 


Originator: 


2278 


Originator: 


2279 


Originator: 


2280 


Originator: 


2281 


Originator: 


2282 


Originator: 


2283 


Originator: 


2284 


Originator: 


2285 


Originator: 


2286 


Originator: 


2287 


Originator: 


This message alias already exists locally. 


NERR_AlreadyExists 


The maximum number of added message aliases has been exceeded. 


NERR_TooManyNames 


The computer name cannot be deleted. 


NERR_DelComputerName 


Messages cannot be forwarded back to the same workstation. 


NERR_LocalForward 


Error in domain message processor. 


NERR_GrpMsgProcessor 


The message has been sent but the reception is currently paused. 


NERR_PausedRemote 


The message was sent but not received. 


NERR_BadReceive 


The message alias is currently in use—try again later. 


NERR_ NamelInUse 


The messenger service has not been started. 


NERR_MsgNotStarted 


The name is not on the local computer. 


NERR_NotLocalName 


The forwarded message alias cannot be found on the network. 


NERR_NoForwardName 


The message alias table on the remote station is full. 


NERR_RemoteFull 
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Server 


2288 Messages for this alias are not currently forwarded. 


Originator: NERR_NameNotForwarded 


2289 The broadcast message was truncated. 


Originator: NERR_TruncatedBroadcast 


2290 An error occurred in reading the message file. 


Originator: NERR_FileError 


2294 This is an invalid device. 
Originator: NERR_InvalidDevice 


2295 A write fault has occurred. 
Originator: NERR_WriteFault 


2297 A duplicate message alias exists on the local area network. 


Originator: NERR_DuplicateName 


2298 This message alias will be deleted later. 
Originator: NERR_DeleteLater 


2299 The message alias was not successfully deleted from all networks. 


Originator: NERR_IncompleteDel 


2300 This operation is not supported on machines with multiple networks. 
Originator; NERR_MultipleNets 


An OS/2 LAN Requester/Server API function returning error codes 2310 to 2329 
encountered an error when processing information about a server. 


2310 This shared resource does not exist. 


Originator: NERR_NetNameNotFound 


2311 This device is not shared. 
Originator: NERR_DeviceNotShared 
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Serial Device 


2312 A session does not exist with that computer name. 


Originator: NERR_ ClientNameNotFound 


2314 There is not an open file with that ID number. 
Originator: NERR_FileldNotFound 


2315 A failure occurred when executing a remote administration command. 


Originator: NERR_ExecFailure 


2316 A failure occurred when opening a remote temporary file. 


Originator: NERR_TmpFile 


2317 The data returned from a remote administration command has been 
truncated to 64KB. 


Originator: NERR_ TooMuchData 


2318 This device cannot be shared as both a spooled and a non-spooled device. 


Originator: NERR_DeviceShareConflict 


2319 The server table was initialized incorrectly. 


Originator: NERR_BrowserTableIncomplete 


2320 This domain is not active on this computer. 


Originator: NERR_NotLocalDomain 


An OS/2 LAN Requester/Server API function returning error codes 2330 to 2349 
encountered an error with a serial device. 


2331 The operation is invalid for this device. 
Originator: NERR_DevIinvalidOpCode 


2332 This device cannot be shared. 
Originator: NERR_DevNotFound 


2333 This device was not open. 


Originator: NERR_ DevNotOpen 
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2334 This device name string is invalid. 
Originator: NERR_BadQueueDevString 


2335 The queue priority is invalid. 
Originator: NERR_BadQueuePriority 


2337 There are no shared communication devices. 


Originator: NERR_NoCommDevs 


2338 A queue does not exist for this request. 
Originator: NERR_QueueNotFound 


2340 This list of devices is invalid. 
Originator: NERR_BadDevString 


2341 The requested device is invalid. 
Originator; NERR_BadDev 


2342 This device is already in use by the spooler. 
Originator: NERR_InUseBySpooler 


2343 This device is already in use as a communications device. 


Originator: NERR_CommDevInUse 


VO 


An OS/2 LAN Requester/Server API function returning error codes 2350 to 2369 
encountered an error while processing input or output. 


2351 The specified computer name is invalid. 


Originator: NERR_InvalidComputer 


2354 The string and prefix specified are too long. 
Originator: NERR_MaxLenExceeded 


2356 This path component is invalid. 
Originator: NERR_BadComponent 
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2357 The type of input cannot be determined. 
Originator; NERR CantType 


2362 The buffer for types is not big enough. 
Originator: NERR_ TooManyEntries 


Audit Log and Error Log 


Remote Error 


An OS/2 LAN Requester/Server API function returning error codes 2377 to 2379 
encountered an error writing or reading from the audit log file or error log file. 


2377 This log file exceeds the maximum defined size. 
Originator: NERR_LogOverflow 


2378 This log file has changed between reads. 
Originator: NERR_LogFileChanged 


2379 This log file is corrupt. 
Originator: NERR_LogFileCorrupt 


An OS/2 LAN Requester/Server API function returning error codes 2380 to 2399 
encountered an error while executing a remote process. 


2380 The source path cannot be a directory. 
Originator: NERR_SourcelsDir 


2381 The source path is illegal. 
Originator: NERR_BadSource 


2382 The destination path is illegal. 
Originator: NERR_BadDest 


2383 The source and destination paths are on different servers. 


Originator: NERR_DifferentServers 


2385 The run server you requested using the NET RUN command is paused. 
Originator: NERR_ RunSrvPaused 
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2386 An error was detected while creating a thread. 
Originator: NERR_CreatingThread 


2387 An error was detected while creating a pipe. 
Originator: NERR_ErrorMakingPipe 


2389 An error occurred when communicating with a run server. 


Originator: NERR_ErrCommRunSrv 


2390 An error occurred when connecting to run server. 


Originator: NERR_ErrConnRunSrv 


2391 An error occurred when starting a background process. 


Originator: NERR_ErrorExecingGhost 


2392 The shared resource you are connected to could not be found. 


Originator: NERR_ShareNotFound 


Requester Redirector 


An OS/2 LAN Requester/Server API function returning error codes 2400 to 2429 
encountered an error with the requester redirector. 


2400 The LAN adapter number is invalid. 
Originator: NERR_InvalidLana 


2401 There are open files on the connection. 


Originator: NERR_OpenFiles 


2402 Active connections still exist. 


Originator: NERR_ActiveConns 


2403 This netname or password is invalid. 


Originator: NERR_BadPasswordCore 


2404 The device is being accessed by an active process. 
Originator: NERR_DevInUse 


C-18 LAN Server Application Programmer’s Reference 


2405 The drive letter is in use locally. 
Originator: NERR_LocalDrive 


2406 Cannot allocate sufficient memory to load requester software. 
Originator; NERR_ MemAllocMsg 


2407 Error reading NETWORKS entry in the IBMLAN.INI file. 
Originator: NERR_IniFilRdErr 


2408 Too many NETWORKS entries in the IBMLAN.INI file. 
Originator; NERR_MultNetsMsg 


2409 NETWORKS entry in the IBMLAN.INI file is too long and is ignored 
Originator: NERR_BadNetEntHdr | 


2410 Error opening a network device driver. 


Originator: NERR_BadBiosMsg 


2411 There has been an improper BiosLinkage response from a device driver. 


Originator: NERR_BadLinkMsg 


2412 Argument given to the function is not valid. 
Originator: NERR_BadArgMsg 


2413 Incorrect OS/2 version in use. 


Originator: NERR_BadVerMsg 


2414 A redirector is already started. 
Originator: NERR_RdrInstMsg 


2415 Drive in local use. 


Originator: NERR_LocalDrive 


2416 Error starting the NETWKSTA.SYS. 
Originator: NERR_Version 
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2430 The specified client is already registered for the specified event. 
Originator: NERR_AlertExists 


2431 The Alerter service table is full. 
Originator: NERR_TooManyAlerts 


2432 The Alerter service has not been started. 


Originator: NERR_NoSuchAlert 


2433 The Alerter service recipient is invalid. 


Originator: NERR_BadRecipient 


2440 The log file does not contain the requested record number. 


Originator: NERR_InvalidLogSeek 


2450 The UAS data2450 is not configured correctly. 
Originator: NERR_BadUasConfig 


2455 The Netlogon service has not been started. 
Originator: NERR_NetLogonNotStarted 


2456 It is not possible to grow the UAS file. 
Originator: NERR_CanNotGrowUASFile 
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Appendix D. Creating OS/2 LAN Server Services 


When designing a service to use with the OS/2 LAN Requester/Server software, keep 
in mind the following requirements: 


e An executable file of a service must be listed under the SERVICE component 
section in the IBMLAN_INI file. 


e A service must not call screen or keyboard functions; this can be done indirectly 
by calling a pop-up function such as VioPopup (an OS/2 program function). 


e A service must dynamically notify the OS/2 LAN Requester/Server software 
about a change in its status by calling the NetServiceStatus function, so that 
other applications can respond correctly to the change. 


e A service must respond to any signal sent by an application, calling the 
NetServiceControl function to change its current state of operation. 


An IBMLAN.INI entry of a service must include the name of the service and a valid 
path name of an executable file used to start the service, and can have additional 
parameters supply other information. Applications requesting to use the service can 
call the functions in the Configuration category to obtain the additional information. 
For information on using the Configuration functions and a description of 
IBMLAN.INI components, see “Configuration Category” on page 3-68. 


Starting a Service 


After a service is started on a computer, the service must: 


1. Call the NetServiceInstall function to notify the OS/2 LAN Requester/Server 
software that a service is being started. 


2. Verify any command-line parameters passed to the service by the calling process. 
3. Start a signal-handler to interpret opcodes that requesting applications pass. 


4. Set its state to INSTALL_PENDING to notify any requesting applications that 
it is not ready for use, by calling the NetServiceStatus function. 


5. Complete any other initialization procedures previously defined by the service. 


6. Notify the OS/2 LAN Requester/Server software that installation is complete by 
calling the NetServiceStatus function and setting its state to INSTALLED. 


NetServiceInstall executes the executable file specified in the IBMLAN.INI 
component of the service by calling the OS/2 DosExecPgm function and passing the 
string of parameters comprised of IBMLAN.INI parameters and information passed 
to the cmdargs parameter of NetServicelnstall. 


The DosExecPgm function executes the service in detached mode, preventing handles 
from being passed to child processes and preventing screen- and keyboard-oriented 
calls except through pop-up functions. A service inherits the environment of the 
parent process—the NetServiceInstall function. 


If a service includes more than one process, the process that DosExecPgm initially 
executes, referred to as the main service process, is the only process that receives 
standard signals from NetServiceControl. The main service process is the only one 
that can issue calls to the NetServiceStatus function. A service can transfer the 
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responsibilities of the main service process to another process by setting the pid 
component of the service_status data structure (passed to NetServiceStatus) to the 
process identification number (PID) of the main service process candidate. 


After receiving control from the DosExecPgm function, a service validates the 
parameters passed from the IBMLAN.INI file. If the parameters are invalid, a 
service notifies the OS/2 LAN Requester/Server software by calling the 
NetServiceStatus function and ending execution. Otherwise, the service installation 
continues. 


After verifying parameters, a service must start a signal-handler that communicates 
with the NetServiceControl function. Using the signal-handler, a service specifies its 
current state (such as INSTALL_PENDING or INSTALLED) for the OS/2 LAN 
Requester/Server software to enable other applications to properly use the service. 
The signal-handler must register a function for the FlagA signal, opcode 
SERVICE_REC SIG FLAG by calling the DosSetSigHandler function. 


The following pseudocode illustrates the general format for a signal-handler: 


void far pascal 

signal_handler (sig_arg, sig_no) 
unsigned sig_arg; 

unsigned sig_no; 


struct service_status svci; 


unsigned char opcode; /* opcode parameter from 

the NetServiceControl function */ 
unsigned char arg; /* arg parameter from 

the NetServiceControl function */ 


il 


opcode 
arg 


(unsigned char) (sig_arg & Oxff); 
(unsigned char) ((sig_arg) >> 8) & Oxff); 


/* set up default values for NetServiceStatus buffer */ 
svci.svcs_pid = 0; 
svci.svcs_ status = SERVICE_INSTALLED | SERVICE_UNINSTALLABLE; 
svci.svcs_code = OL; 
switch (opcode) { 

case SERVICE_CTRL_INTERROGATE : 


set_wksta_status (& svci); 
break; 


/* other opcodes as appropriate 


*/ 
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case SERVICE_CTRL_UNINSTALL : 


svci.svcs status = SERVICE_UNINSTALL_PENDING; 
set_wksta_status = (& svci); 


Terminate (); 
default : 


/* treat all unknown commands 
as SERVICE_CTRL_INTERROGATE */ 
} 


/* issue a 'reset' for the signal */ 
DosSetSigHandler (0, 0, 0, SIG_RESET, sig_no); 


return; 


/* 
Note that if the signal-handler is written in C, it must be 
compiled using the auto-load DS option (-A option). 
Otherwise, the DS register will not be loaded to the 
service's default data segment when the signal-handler 
is called, and the code in the handler may make incorrect 
assumptions about the data's location. 


Signal-handlers must preserve registers as noted 
in the 0S/2 programming documentation. 


*/ 
} 


After a service specifies its current state as INSTALLED, another application can 
change or query the state of the service by calling NetServiceControl. With this 
function, an application can pass an opcode specifying one of four actions to take, 
as defined in SERVICE.H, as follows: 


Manifest Value Meaning 

SERVICE_CTRL_INTERROGATE 0 Request for general 
information. 

SERVICE_CTRL_PAUSE 1 Pause the service. 

SERVICE_CTRL_CONTINUE 2 Continue a paused 
service. 

SERVICE _CTRL_UNINSTALL 3 Shut a service down. 


A service can define its own set of valid opcodes. Invalid opcodes should default to 
another opcode such as SERVICE_CTRL_INTERROGATE. The OS/2 LAN 
Requester/Server software defines the following limits: 


e A service that does not accept the SERVICE UNINSTALL opcode cannot be 
removed at any time. 
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¢ While in the SERVICE_INSTALL_PENDING state, a service can receive only 
the SERVICE_UNINSTALL opcode. 


In the following pseudocode, an application and a service communicate by means of 
a signal-handler and the OS/2 LAN Requester/Server software: 


Application 0S/2 LAN Requester/Server Service 


application calls 
NetServiceControl 
specifying an 
opcode to perform 
a particular task 
| 
| opcode is sent 
+--->>------ to the specified 
service 
| 
| signal-handler 
+---->>----- interprets opcode 
| 
performs the task 
defined by the opcode 
| 
calls NetServiceStatus 
to change the state of 
the service, if required 
| 
updates service ---<<---+ 
information table 
according to current 
state of the service 
| 
| 
NetServiceControl | 
returns with the -<<-+ 
appropriate information 
about the service's 
current state 


If performing the task takes a long time (more than a few seconds), the service 
should make intermediate calls to the NetServiceStatus function. 


Stopping a Service 


When a service is no longer needed, either the application using it or the service itself 
should call NetServiceControl and specify the appropriate shut-down opcode. After 
receiving a shut-down opcode, a service must again call NetServiceStatus to declare 
SERVICE_UNINSTALL_PENDING status and then perform any other necessary 
tasks, such as closing open resources. The final step is to call the OS/2 DosExit 
function. Immediately before doing this, the service must again change its status, 
this time to SERVICE_UNINSTALLED. 


For an application to disable a service from processing any further requests, the 
service performs the following steps: 
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¢ Call NetServiceStatus to set a SERVICE UNINSTALL PENDING state 
e Execute a cleanup routine, closing any open resources 


°¢ Notify the OS/2 LAN Requester/Server software that it has been removed by 
calling NetServiceStatus and setting a SERVICE_UNINSTALLED state 


e End program execution. 


To obtain information about services started, an application calls NetServiceEnum. 
To query the state of a service, retrieving its status and code information, an 
application calls NetServiceStatus. 


The following pseudocode illustrates how the alerter service communicates with 
other services, applications, and the OS/2 LAN Requester/Server software: 


spooler (print alerts) -->>---+ 


server (security alerts) ->>--+ 


NetAlertRaise -->>-+ 


Other Services ------ >>------------- + | 


Other Applications ---->>------------ + | 


text event | 
NetMessageBufferSend -<<- ALERTER Service ---<<----+ 


local mailslot 


Remote Messenger 
Service 


For information on the default OS/2 LAN Requester/Server services and the 
functions used to control services, see “Service Category” on page 3-298. 
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Appendix E. OS/2 LAN API Support under IBM DOS 


Requesters 


Chapter 3, “API Function Descriptions,” contains detailed descriptions of the OS/2 
LAN Requester/Server API functions. This appendix presents information 
programmers should be aware of when using OS/2 LAN Requester/Server APIs with 
DOS Requester. 


In this appendix, you will find information about: 
e IBM DOS API services 
¢ IBM DOS libraries, where they are stored, and which ones are needed 


e API functions supported under IBM DOS and any differences in their use. 


Note: When porting OS/2 LAN Requester/Server applications to run under DOS, 
be aware that DOS, unlike the OS/2 program, does not support pointer checking, 
semaphores, or shared memory segments. Also note that all file names, directory 
names, or parts of a path name, including UNC server and share names, must follow 
DOS naming conventions. 


API Services Supported Under DOS 


DOS Requester supports the following services: 


Service Purpose 

messenger Enables applications to send messages across the LAN. 

netpopup Enables messages to be displayed as pop-up messages on the 
screen. 

requester Enables DOS computers (attached to the LAN) to be configured 
as requesters, thus enabling them to access resources on remote 
OS/2 LAN servers. 


These services are installed during installation of the redirector program. Unlike the 
OS/2 program, the services cannot be completely stopped once they are installed. 
However, they can be paused and continued using the NetServiceControl function. 


DOS API Libraries 
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The OS/2 program uses dynamically-linked libraries during run time; DOS does not. 
Under DOS, link your application with either the DOSNET.LIB or WINNET.LIB 
library and the SYSCALLO.LIB library. 


The DOSNET.LIB and SYSCALLO.LIB libraries also serve as BIND libraries for 


the OS/2 NETAPI.LIB, NAMEPIPE.LIB, MAILSLOT.LIB, and NETSPOOL.LIB 
libraries (similar to the API.LIB library). 
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The following sample commands show which DOS libraries to link in with your 
application to achieve the same functionality that NETAPI.LIB provides: 


LINK mydosap.obj, mydosap.exe, mydosap.map /MAP, 
c:\ibmlan.dos\netsrc\1ib\dosnet.1ib 


BIND myos2ap.exe doscalls.1ib c:\ibmlan.dos\netsrc\lib\netapi.1ib 
c:\ibmlan.dos\netsrc\1ib\dosnet.1ib 
c:\ibmlan.dos\netsrc\lib\syscal10.1ib api.lib 


The SYSVALLO.LIB library file supports networking functions when using the OS/2 
FAPI system calls (DosOpen, DosBufReset, DosRead). If used, it must immediately 
precede the API.LIB file name as shown in the preceding BIND command line. 

The default storage location for dosnet.lib, syscall0.lib, and winnet.lib is 
c:\ibmlan.dos\netsrc\lib. 


Include Files 


DOS Requester uses most of the OS/2 include files described in Appendix A, 
“Include Files.” The include files are stored by default in 


c:\ibmlan.dos\netsrc\h. 


The following include files are used under DOS: 


API Category Include Files API Category _Include Files 
Access NETCONS.H Profile NETCONS.H 
Permission ACCESS.H PROFILE.H 
Configuration NETCONS.H Remote NETCONS.H 
CONFIG.H Utility REMUTIL.H 
Mailslot NETCONS.H Server NETCONS.H 
MAILSLOT.H SERVER.H 
Message NETCONS.H Service NETCONS.H 
MESSAGE.H SERVICE.H 
Session NETCONS.H 
SHARES.H 
Share NETCONS.H Named Pipe NETCONS.H 
SHARES.H NMPIPE.H 
ACCESS.H 
Use NETCONS.H User NETCONS.H 
USE.H ACCESS.H 
Requester NETCONS.H 
WKSTA.H 
ACCESS.H 
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Differences in Use Under DOS 


DOS Requester supports a subset of the API functions described in Chapter 3, “API 
Function Descriptions.” Most of the DOS Requester API functions are executed on 
a remote server. API functions that can be executed remotely must include a remote 
server name parameter to identify where the function is to be executed. Attempting 
to execute a remote only function on a local requester returns NERR_RemoteOnly. 


Those functions that can be executed on a local requester must be called with a 
NULL server name parameter (defaults to local requester name) or the name 
assigned the local requester in the format—computer name. Attempting to execute a 
local only function on a remote server returns ERROR_NOT_SUPPORTED. 


The following sections describe the API functions that DOS LAN Requester 
supports. In the descriptions, both the categories and the functions within each 
category are alphabetically listed along with any differences in their use from that 
described in Chapter 3, “API Function Descriptions.” 


Access Permission 


Auditing 


The functions in the Access Permission category examine or modify user or group 
access permission records for server resources. Under DOS, these functions can only 
be executed on a remote server. Administrative privilege must have been granted to 
execute the functions. Attempting to execute the functions on a local requester 
returns NERR_RemoteOnly. 


Function Differences in Use 
NetAccessAdd (admin) None 
NetAccessDel (admin) None 
NetAccessEnum (partially 

admin) None 
NetAccessGetInfo (partially 

admin) None 
NetAccessGetUserPerms 

(partially admin) 

NetAccessSetInfo (admin) None 

Function Differences in Use 
NetAuditClear (local) None 
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Configuration 


Connection 


Error Logging 


File 


Group 


The functions in the Configuration category cannot retrieve network configuration 
information from the DOSLAN.INI file. However, these functions can be called 
remotely on a DOS requester to retrieve information from the IBMLAN_INI file. 


Function 


NetConfigGet2 (admin, DOS) 


NetConfigGetAll2 (admin, 
DOS) 


Function 


NetConnectionEnum (local) 


Function 
NetErrorLogClear (local) 
NetErrorLogRead (local) 


Function 
NetFileClose2 (local) 
NetFileEnum2 (local) 
NetFileGetInfo2 


Function 

NetGroupAdd (local) 
NetGroupAddUser (local) 
NetGroupDel (local) 
NetGroupDel User (local) 
NetGroupEnum (local) 
NetGroupGet Users (local) 
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Differences in Use 
Cannot be called locally on a DOS requester 


Cannot be called locally on a DOS requester 


Differences in Use 


None 


Differences in Use 


None 


Differences in Use 
None 


None 


Differences in Use 
None 
None 
None 
None 
None 


None 


Mailslot 


Message 


The functions in the Mailslot category provide one-way interprocess communication 
(IPC). Under DOS, the functions can be executed on a local requester or remote 
server. 


Note that mailslots can only be read or deleted by the process that created them. 
Mailslots created by a process are deleted when that process ends. 


Function Differences in Use 
DosDeleteMailslot None 
DosMailslotInfo None 
DosMakeMailslot None 
DosPeekMailslot None 
DosReadMailslot None 
DosWriteMailslot None 


The functions in the Message category are used to send and receive messages. The 
functions can be executed only on a local requester. Attempting to execute the 
functions on a remote server returns ERROR_NOT_SUPPORTED. 


Under DOS, messages cannot be forwarded, unforwarded, or logged. 


By default, DOS LAN Requester accepts only two names in the message name table: 
the name of the requester and the name of the user. To define more names, edit the 
DOSLAN.INI file and change the value of the nmsg parameter for the messenger 
component. For more information on the DOSLAN.INI file, see the DOS User's 
Guide. 


The maximum size of a message under DOS is 64KB. 


Function Differences in Use 


NetMessageBufferSend (local) Under DOS, the name parameter cannot point 
to the name of the local requester or to the users 
currently logged on to that requester. 


NetMessageFileSend (local) Under DOS, the name parameter cannot point 
to the name of the local requester or to the users 
currently logged on to that requester. 


NetMessageLogFileGet (local) None 
NetMessageLogFileSet (local) None 
NetMessageNameAdd (local) None 
NetMessageNameDel (local) None 
NetMessageNameEnum (local) None 


NetMessageNameFwd (local) None 
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Function Differences in Use 


NetMessageNameGetInfo None 
(local) 
NetMessageNameUnFwd None 
(local) 


Named Pipe 


The functions in the Named Pipe category control interprocess communication (IPC) 
for named pipes. The functions can be executed only on a remote server which has 
interprocess communication shares. 


DOS supports only client processes; a pipe must have already been created and 
connected on a remote server. Child processes inherit the open file handles of the 
parent processes. DOS does not support asynchronous reading and writing of 
named pipes. 


Note: The FAPI replacement library routine for DosOpen provides support for 
DASD opens (open Mode Flag 0x8000). Since DOS does not support this operation, 
pipe operations on this type of file handle return ERROR_INVALID_HANDLE 
rather than ERROR_BAD PIPE. 


Function Differences in Use 


DosBufReset DosBufReset works differently depending on the 
version of DOS you are programming under. 
Under versions 3.3 and 4.0, DosBufreset returns 
0 after resetting a closed named pipe. If the 
handle is to a named pipe that has already been 
closed, DosBufReset returns 
ERROR_BROKEN PIPE. 


Under DOS 3.3 and 4.0, DosBufReset waits for 
the pipe to be emptied before resetting it. 


DosCallNmPipe None 
DosClose None 
DosDupHandle None 
DosOpen None 
DosPeekNmPipe None 
DosQHandType None 
DosQNmpHandState None 
DosQNmPipelnfo None 
DosRead None 
DosSetNmpHandState None 
DosTransactNmPipe None 
DosWrite None 
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Remote Utility 


Requester 


Serial Device 


The functions in the Remote Utility category enable applications to copy and move 
remote files, and access the time-of-day information on a remote server. Attempting 
to execute the functions on a local requester returns NERR_RemoteOnly. 


Function 

NetRemoteCopy (Server) 
NetRemoteMove (Server) 
NetRemoteTOD (Server) 


Differences in Use 
None 
None 


None 


The functions in the Requester category control the operation of requesters. They 
can be executed only on a local requester. Attempting to execute the functions on a 
remote server returns ERROR _NOT_SUPPORTED. 


Function 
NetWkstaGetInfo (local) 
NetWkstaSetInfo (local) 
NetWkstaSetUID2 (local) 


Differences in Use 
None 
None 


None 


Certain parameters are not used under DOS and therefore cannot be set. However, 
validity checks are performed on most of the unused parameters for future 
expansion. The following table describes the parameters that are used and indicates 
whether validity checks are performed on them: 


Parameter Used 
charwait No 
chartime Yes 
charcount Yes 
errlogsz No 
printbuftime No 
wrkheuristics No 
Function 

NetCharDevControl (local) 
NetCharDevEnum (local) 


NetCharDevQEnum (local) 
NetCharDevQGetInfo (local) 
NetCharDevQPurge (local) 
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Validity Checked 
Yes 
Yes 


Differences in Use 
None 
None 
None 
None 


None 
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Function Differences in Use 
NetCharDevQPurgeSelf (local) None 
NetCharDevQSetInfo (local) None 


Server 
The functions in the Server category enable remote administration tasks to be 
performed on a remote server. NetServerEnum can be executed on either a local 
requester or remote server; all other server functions are executed on a remote server. 
Attempting to execute NetServerAdminCommand or NetServerGetInfo on a local 
requester returns NERR_RemoteOnly. 
Function Differences in Use 
NetServerAdminCommand None 
(Server) 
NetServerDiskEnum (Server, Usually called locally (same as the OS/2 
local) | program) 
NetServerEnum2 None 
NetServerGetInfo (Server) None 
NetServerSetInfo (Server) None 
Service 
The functions in the Service category control network service programs. They are 
executed on a local requester. Attempting to execute the functions on a remote 
server returns ERROR_NOT_SUPPORTED. 
Under DOS, the services cannot be completely stopped; however, they can be paused 
and continued using NetServiceControl. 
Function Differences in Use 
NetServiceControl (local) None 
NetServiceEnum (local) None 
NetServiceGetInfo (local) None 
NetServiceInstall (local) None 
Session 
Function Differences in Use 
NetSessionDel None 
NetSessionEnum None 
NetSessionGetInfo None 
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Share 


Statistics 


Use 


User 


The functions in the Share category control shared resources. They can be executed 
only on a remote server. Attempting to execute the functions on a local requester 


returns NERR_RemoteOnly. 


Function 
NetShareAdd 
NetShareCheck 
NetShareDel 
NetShareEnum 
NetShareGetInfo 
NetShareSetInfo 


Function 


NetStatisticsGet2 


Differences in Use 
None 
None 
None 
None 
None 


None 


Differences in Use 


None 


The functions in the Use category examine or control connections (uses) between 
requesters and servers. They can be executed only on a remote server. Attempting to 
execute the functions on a local requester returns NERR_RemoteOnly. 


Function 

NetUseAdd (local) 
NetUseDel (local) 
NetUseEnum (local) 
NetUseGetInfo (local) 


Differences in Use 
None 
None 
None 


None 


The NetUserPasswordSet function controls a user’s password account on a server. 
NetUserPasswordSet can be executed only on a remote server running user-level 
security. Attempting to execute it on a local requester returns NERR_RemoteOnly. 


Function 
NetUserAdd 
NetUserDel 
NetUserEnum 
NetUserGetGroups 
NetUserGetInfo 


Differences in Use 
None 
None 
None 
None 


None 
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Function Differences in Use 
NetUserPasswordSet None 
NetUserSetInfo None 
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Appendix F. IBM C/2 Sample Program 


The following is a sample IBM C/2 program for the OS/2 LAN Server Version 1.2 

application programming interface. 

fPRESROSERE ASSET ER EE SPER EEAE SESS ORT REER ALR ORAM ERN EA ANENSAR SERS ORE RNY 

/* 

/* FILE NAME SHARENUM.C 

j* 

/* MODULE NAME= SHARENUM.C 

/* 

/* DESCRIPTIVE NAME= C SAMPLE PROGRAM FOR THE LAN SERVER 1.2 API 
/* 

/ * 

/* COPYRIGHT: XXXXXXXXX (C) COPYRIGHT IBM CORP. 1989 - 
. LICENSED MATERIAL - PROGRAM PROPERTY OF IBM 

[* ALL RIGHTS RESERVED 

{* 

/* 

/* NOTES= 

/* 


[REEPFESEERERESEREEE SER E END OF SPECIFICATIONS —*¥ 4 ex RRR R HRA AKER KKK 


* SHARENUM.C 


* 


+ + $+ + FF F HF F 


+ + + F F F 


Invocation: Invoke this program from the 0S/2 full-screen 
command prompt by typing: 


SHARENUM [\\SERVERNAME] LEVEL 


Where SERVERNAME is the name of the remote server and LEVEL 
is the level of the share_info data structure to be returned. 
If SERVERNAME is not specified, the program will execute on 
the local server. Valid values for LEVEL are 0, 1, and 2. 


Output: The program outputs information using the printf function, 
depending on the level with which it is called: 
LEVEL = 0 
For each shared resource, the netname of the resource. 
LEVEL = 1 
For each shared resource: 
the netname 
the type 
the remark 
LEVEL = 2 
For each shared resource: 
the netname 
the type 
the remark 
the maximum number of uses 
the current number of uses 
the directory path to the resource on the server 


Functions: This program consists of two functions: main and InfoOut. 
The main function parses the command line, then calls 
NetShareEnum to find out how many shares are available. 


+ Fe FF Fe FE FF FH FF KE HF HF HF HF HF HF HF HF HF HF KF HF HF KF HF HF HF HF HF HF F 
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e+ F * $F HF FHF HF HF HF F 


* 
SS 


[BEREREERREERERA RES AENAERARERE AAS 


* Include Files 


* 


RERAAL ES LAS EA RANON ERROR ERS NSC) 


#include <stdio.h> 
#include <stdlib.h> 
#include <ctype.h> 
#include <process .h> 
#include <os2.h> 
#include <neterr.h> 
#include <netcons.h> 
#include <shares.h> 
#include <access.h> 


[= 


Declares the printf() function 
Declares the atoi() function 
Declares the isdigit() function 
Declares the exit() function 
Defines OS/2 constants and data 
Defines Network error codes 
Defines Network constants 
Required by NetShareEnum 
Required by NetShareEnum 


Forward Declaration of InfoOut **/ 


void InfoOut (int, char *, unsigned short); 


PSEESEEERERERS ELE LARD AREANAN TERA SR ERE SEES EERS 


* main 


* 


AERENAERARAN RARE RERENENEYREWAESNEEERENEE EAS 


main(argc, argv) 
int argc; 
char *argv[]; 


int 

char 

char 

short 

unsigned short 
unsigned short 
unsigned short 


The actual number of shares is then used to calculate the 
buffer length, based on the level of information requested. 
NetShareEnum is then called a second time with this buffer. 
If no error is returned, main then calls InfoOut, passing 
the level, a pointer to the buffer, and the number of shares 
returned by the API. 
The InfoOut function uses the printf function to output the 
share information, based on the level. 


| 
oh 
Ay 
o/ 


structures */ 


/* API return code storage */ 


IZ string */ 


/* Pointer to a buffer area */ 


rc=0; 
*servername; /* Pointer to ASCI 
*buf; 

level=0; /* Level of s 
buflen=0; 


entriesread=0; 
totalentries=0; 


hare info */ 


/* Size of buffer area */ 


/* Number of shares 


/* Number of shares returned */ 


available */ 


[PRAIA NAEASAA TARE REAEEANER ERE ER ANANS SERED ERR EREERER ER ER EAA RAO R ARLE ROO Dp 


/* Begin command line parsing */ 


switch (argc) 


case 1: 
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/* Not enough arguments, return syntax */ 
printf ("\nSyntax: sharenum [\\\\servername] level\n\n"); 
printf ("Where servername is the name of the remote server\n"); 


printf ("and level is a digit (0, 1, or 2) specifying the\n"); 
printf ("level of share information. If \\\\servername is not\n"); 
printf ("specified, the call is executed locally.\n\n"); 

exit(1); 

break; /* case 1 */ 


case 2: /* Only 1 parameter is passed to sharenum; */ 
/* assume a null servername and test for a */ 
/* valid level. */ 
if ( strlen(argv[1]) > 1 ) /* String must be of Tength 1 */ 
{ 


printf ("Level must be an integer between 0 and 2.\n"); 
exit(1); 


else /* Test for a digit */ 
if ( isdigit (argv[1][0]) == 0 ) 
{ 


printf ("Level must be an integer between 0 and 2.\n"); 


exit(1); 
} 
else 
level = atoi(argv[1]); /* argv[i] is a digit */ 
servername = "\0"; /* Assign null servername */ 
} 


} /* end else strlen */ 


break; /* case 2 */ 


case 3: /* Both servername and level are passed; */ 
/* test for a valid level. */ 
if ( strlen(argv[2]) > 1 ) /* Level string must be of length 1 */ 
printf ("Level must be an integer between 0 and 2.\n"); 
exit(1); 
} 
else 
if ( isdigit (argv[2][0]) == 0 ) /* Test for a digit */ 
{ 
printf ("Level must be an integer between 0 and 2.\n"); 
exit(1); 
} 
else 
level = atoi(argv[2]); /* argv[2] is a digit */ 
servername = argv[1]; /* argv[i] is the servername */ 


/* Note: servername MUST BEGIN WITH \\ */ 
} 
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} /* end else strlen */ 
break; /* case 3 */ 


} /* end switch(argc) */ 


if ( level > 2 ) /* level must be 0, 1, or 2 */ 
{ 
printf ("Level must be an integer between © and 2.\n"); 
exit(1); 
} 
/* End command line parsing. *7 


Ja REREAAEAA ELSA ERAS ADEA EASA SE ASAR ORAS AAAS RSS ER EARAPR ATA NNO SSE AD) 


/* First call NetShareEnum to find out how many shares are available. 
The number of shares available will be given by the totalentries 
parameter. + 


buflen = 0; /* Zero buffer length should cause error */ 


rc = NetShareEnum ( (char far *) servername, 
level, 
(char far *) buf, 
buflen, 
(unsigned short far * ) &entriesread, 
(unsigned short far * ) &totalentries); 


if ( rc == NERR Success ) /* No shares on server */ 
{ 

printf ("\nServername: %s  ", servername); 

printf ("Level: %d ", level); 

printf ("Return code from Enum: %d\n", rc); 

printf ("Entries read: %u  ", entriesread); 

printf ("Total entries: %u\n", totalentries); 

printf ("\nNo resources are shared.\n\n"); 


exit (0); 
} 
else if ( rc != ERROR_MORE_DATA ) /* Some unexpected error */ 
{ 


printf ("\nServername: %s =", servername) ; 
printf ("Level: %d ", level); 
printf ("Return code from Enum: %d\n", rc); 
printf ("\nCall to NetShareEnum failed.\n\n"); 
exit (2); 

} 


/* Now we know the total number of entries and can calculate buflen, 
based on the level, as follows: */ 


switch (level) 


case 0: 
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buflen = (sizeof(struct share_info_0)) * totalentries; 
break; 


case 1: 
buflen = ((sizeof(struct share_info_1)) 
+ (MAXCOMMENTSZ + 1)) 
* totalentries; 
break; 
case 2: 
buflen = ((sizeof(struct share_info_2)) 
+ (MAXCOMMENTSZ + 1) 
+ (PATHLEN + 1)) 
* totalentries; 
break; 


/* Level is not 0, 1, or 2. Print error message. */ 


default: 
printf ("Level must be an integer between © and 2.\n"); 
exit(1); 

break; 


} /* end switch(level) */ 

/* Allocate the buffer */ 
buf = malloc(buflen); 

/* A null pointer means insufficient memory */ 
: ( buf == '\O' ) 


printf ("Insufficient memory to allocate share-info buffer.\n"); 
exit(2); 
} 


/* API call */ 
rc = NetShareEnum ( (char far *) servername, 
level, 
(char far *) buf, 
buflen, 
(unsigned short far * ) &entriesread, 
{unsigned short far * ) &totalentries); 


printf ("\nServername: %s =", servername) ; 
printf ("Level: %d  ", level); 

printf ("Return code from Enum: %d\n", rc); 
printf ("Entries read: %u  ", entriesread); 
printf ("Total entries: %u\n\n", totalentries); 


/* If no error returned, call InfoOut to output the share info */ 
if ( rc == NERR Success ) 
InfoOut (level ,buf ,entriesread) ; 


/* Free the buffer */ 


free(buf); 
exit(0); 
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/* Note: There is a slight possibility that a share could have been added 
after the first API call such that totalentries would no longer 
reflect the real state of the server. Thus, the buffer could 
be too small at the time of the second API call. More error 
checking could be added to cover this case. */ 


} /* end main */ 


[BRERRRRRERERERERRRERAERIARARERERER ARERR 


* InfoOut * 


RERPENESERLERA ENTERS ERE REN ER ARRAN RENE / 


void InfoOut (Level ,Buf,EntriesRead) 


int Level; /* Level of share info */ 
char *Buf ; /* Pointer to a buffer area */ 
unsigned short EntriesRead; /* Number of shares returned */ 
{ 

int loop; 

struct share_info_ 0 *BufPtr0; /* Pointer to level 0 data */ 
struct share_info_1 *BufPtr1; /* Pointer to level 1 data */ 
struct share_info_2 *BufPtr2; /* Pointer to level 2 data */ 


switch (Level) 


case 0: /* Output level 0 information */ 
BufPtrO = (struct share_info_0 *) Buf; /* type cast */ 
for (loop = 1; loop <= EntriesRead; ++loop) 
{ 
printf("%s \n", BufPtr0->shi0_netname) ; /* print the netname*/ 
BufPtrOQ++3 


} /* end for */ 


break; /* case 0 */ 


case 1: /* Output level 1 information */ 
BufPtr1 = (struct share_info_1 *) Buf; /* type cast */ 


for (loop = 1; loop <= EntriesRead; ++loop) 


{ 

/* Print the netname, type, and remark */ 
printf("Netname: %-12s ", BufPtr1->shil_netname) ; 
printf("Type: %d \n", BufPtr1->shil_type) ; 


printf("Remark: %s \n\n", BufPtr1->shil_remark) ; 
BufPtri++; 
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} /* end for */ 


break; /* case 1 */ 


case 2: /* Output level 2 information */ 
BufPtr2 = (struct share_info 2 *) Buf; /* type cast */ 
for (loop = 1; loop <= EntriesRead; ++loop) 
/* Print the netname, type, remark, maximum number of uses, 
current number of uses, and the path to the resource on 
the server. +7 
printf("Netname: %s ", BufPtr2->shi2_netname) ; 
printf("Type: %d \n", BufPtr2->shi2_type) ; 
printf("Remark: %s \n", BufPtr2->shi2_remark) ; 
printf ("Max Uses: %u ", BufPtr2->shi2_max_uses) ; 
printf("Current Uses: %u\n", BufPtr2->shi2_current_uses); 
printf("Local Path Name: %s \n\n", BufPtr2->shi2_path); 
BufPtr2++; 
} /* end for */ 


break; /* case 2 */ 


} /* end switch */ 


} = /* end InfoOut */ 
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Appendix G. PC LAN Program 1.3 Compatibility 


The DOS LAN Requester with DOS provides several function calls that are not 
described in the main body of this book. These function calls are described here and 
are provided for compatibility with applications currently supported by the PC LAN 
program. 


Function Call Overview 


The following DOS Interrupt function calls are supported by the DOS LAN 


Requester. 
0000 Installation Check 


2AH 0060 Network Print Stream 
Control 
0300 Check Direct 1/0 


Execute NETBIOS (Error 


Execute NETBIOS (No 
Error Retry) 
2AH 0500 Get Network Resource 
Information 
2AH 7802 Get user ID and logon 
status 
2FH B800 DOS LAN Requester 
installation check 
2FH B809 Network version check 



















Function Call Descriptions 
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The following pages contain descriptions of the function calls. 
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0000H (INT 2AH) 


Installation Check 
&pegrule. 


Checks to see if the interrupt 2AH interface is installed 


On Register 
Entry Contents 
2 oie |e: 
On Register 
Return Contents 
AH 


Installed Flag 














Zero s; Not installed 
Non-Zero 3; Installed 


Remarks 
A program can verify whether the interrupt 2AH interface is loaded by calling 
Interrupt 2AH Installation Check. 
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0060H (INT 2AH) 


Network Print Stream Control 


Remarks 


&pgrule. 


Controls the truncation and concatenation of print streams for network printers. 


On Register 
Entry Contents 


A OG os 


01 _ ; Set print output into 
; concatenation mode 
02 __; Set print output into 
On Register 
Return Contents 
AX DOS error code if carry set. 
None if carry flag not set. 
DOS defines separate print streams for each of up to three redirected printers. These 


; truncation mode 
03 __—;s Truncate print stream 

printers are LPT1 (or PRN), LPT2, and LPT3. These print streams are delimited by 

the following events: 













¢ End of program 
¢ Open and close of the files LPT1, LPT2, or LPT3 


¢ Making a transition from printing with the IBM PC BIOS function INT 17H 
and printing with DOS (in both directions) 


¢ Printing with INT 17H from different DOS processes (a process is created by the 
DOS EXEC function). 


DOS is normally in Truncation mode, which means the stream delimiters listed 
above take effect. Concatenation mode (AL=01) causes DOS to ignore the stream 
delimiters. In this mode, the streams are delimited only when a DOS command 
returns to asking for user input. This is either when a single DOS command ends or 
when a DOS Batch (.BAT) ends. This allows output from several commands to be 
kept together if the commands are in a Batch file. Set Concatenation mode changes 
the stream state for all redirected printers. It has no affect on nonredirected printers. 


Set Truncation mode (AL=02) returns DOS to Truncation mode. It is used to 
cancel the Set Concatenation mode function. This call does not truncate streams, 
the next stream delimiter will cause the truncation. Truncation mode is 
automatically set at the end of all DOS batch files and at the end of any command 
not in a batch file. Set Truncation mode changes the stream state for all redirected 
printers. It has no affect on nonredirected printers. 


Not all programs print output in such a way that DOS can determine when a print 


stream ends. Printing using INT 17H is the most common occurance of this 
situation. Truncate Print Stream (AL=03) allows a program to indicate that the 
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data currently printed is a complete stream and it should be ended and printed. This 
function serves the same purpose as the Ctrl+ Alt+PrtSc key that is available to 
users to end print streams. Truncate Print Stream truncates the streams for all 
redirected printers. It has no affect on nonredirected printers. The DOS LAN 
Requester program must be started for this function call to work. 
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0300H (INT 2AH) 
Check Direct I/O 


Remarks 


&pegrule. 

Checks to see if an absolute disk access is allowed to the device. 
On Register 
Entry Contents 
DS:SI Pointer to ASCIIZ disk device name 


On Register 

Return Contents 

Carry flag Set if absolute access is denied 
Clear if access is allowed 





The Check Direct I/O function call provides a check to see if a direct disk access is 
allowed to the specified device. Direct disk access is the use of DOS interrupts 25H 
and 26H or BIOS interrupt 13H. Use Check Direct I/O in programs that perform 
direct disk access. If the device is redirected or this function returns with carry set, 
then the program should not perform direct disk I/O. 


Use Check Direct I/O to eliminate disk data integrity problems that can result from 
multiple concurrent processes updating the DOS disk data structures. 


The device pointed to by DS:SI must include the colon (:). The path may be a full 
path or only the drive specifier. 


Interrupt 2AH (Installation Check) should be done before the Check Direct I/O 
function call. If Interrupt 2A is not installed (AH =0), then absolute disk I/O is 
allowed. Programs should not use the Check Direct I/O function call frequently 
since it may take some time to run. If constant checks are needed, save the results of 
the first check, and check the saved result. 


Note: The DOS LAN Requester must be loaded for the function call to execute 
properly. 
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0400H (INT 2AH) 


Execute NETBIOS (Error Retry) 


Remarks 


&pgrule. 


Executes the specified NETBIOS function call with error retry support provided. 


On Register 
Entry Contents 


ES:BX Pointer to the network control block 
(NCB) 


On Register 

Return Contents 

AH=0, No error 

AL=0 

AH=1, NCB error occurred. AL contains the 
AL=X error code X. 


Execute NETBIOS is reserved for use to support additional functions by capturing 
the intended function call and providing compatibility with extended functions. To 
ensure hardware independence, use the interrupt 2AH function. Do not use the 
interrupt 5CH function provided by the network adapter. 














This function call provides error retry support for the following NETBIOS errors: 


09H - No Resource Available 
12H - Session Open Rejected 
21H - Interface Busy. 


The DOS LAN Requester retries the NETBIOS command that caused the error a 
number of times. To provide their own error recovery support, applications should 
invoke the Execute NETBIOS (0401H) function cail. 


On entry, the ES:BX register pair points to an NCB. 


Note: The DOS LAN Requester must be loaded for the function call to execute 
properly. 
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0401H (INT 2AH) 


Execute NETBIOS (No Error Retry) 


Remarks 


&pegrule. 


Executes the specified NETBIOS function call with no error retry support provided. 


On Register 
Entry Contents 


ES:BX Pointer to the network control block 
(NCB) 


On Register 

Return Contents 

AH=0, No error 

AL=0 

AH=1, NCB error occurred. AL contains the 

AL=X error code X. 
Execute NETBIOS is reserved for supporting additional functions by capturing the 
intended function call and providing compatibility with extended functions. To 


ensure hardware independence, use the interrupt 2AH function call. Do not use the 
interrupt 5CH function provided by the network adapter. 




















This function call does not provide error retry support. (Execute NETBIOS function 
call 0400H provides error retry support.) Applications should provide their own 
error recovery if needed. 


On entry, the ES:BX register pair points to an NCB. 


Note: The DOS LAN Requester must be loaded for the function call to execute 
properly. 
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0500H (INT 2AH) 


Get Network Resource Information 


Remarks 


&pegrule. 


Returns the number of local network names, network commands, and network 
sessions available to an application after the DOS LAN Requester has started. 






On Register 
Entry Contents 


Return Contents 













The get network resource information allows an application to determine how many 
local network resources are available for use after the DOS LAN Requester starts. 
The application should invoke the function call before using any network 

commands. The application should maintain its own network resource count so that 
it does not exceed the values returned from get network resource count. Failure to 
comply with this requirement may cause unpredictable results from both the DOS 


LAN Requester and the network application. 
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7802H (INT 2AH) 


Get User ID and Logon Status 


&pgrule. 


Provides the user ID and logon status information for the current user of the DOS 


LAN Requester program. 


On Register 
Entry Contents 
ES:DI Address of 8 byte buffer 


On Register 

Return Contents 
Zero: No user logged on 
Non-zero: User logged on 

ES:DI Buffer contains user ID, ASCII, padded 
with blanks. 
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B800H (INT 2FH) 


DOS LAN Requester Installation Check 
&pegrule. 


Checks to see if the DOS LAN Requester is installed. If the program is installed, 
Installation Check returns the installed network components. 


On Register 
Entry Contents 
Pax | 


B800H 


On Register 
Return Contents 
AL 


Network installed flag: 








Zero ; Network not installed 
Non-Zero ; Network is installed 


Installed component flag (bit flags): 


XXXXXXXX XXXX1xxx : Redirector 
XXXXXXXX LXXXXxxx : Receiver 





Note: The x represents an undefined value. 


Assembler Usage 


MOV AX,B800H 3sAX - function code 

INT 2FH 3Call function 

CMP AL,.O 3Is network installed? 

JE NOT_INSTALLED sNo, network not installed 

TEST BX,RECEIVER_FLAG 3Is Receiver installed? 

JNZ RECEIVER_STARTED 3Yes, Receiver is installed 

TEST BX,REDIRECTOR_FLAG 3Is Redirector installed? 

JNZ  REDIRECTOR_ STARTED sYes, Redirector is installed 
Remarks 


Use interrupt 2F (Installation Check) to determine if the DOS LAN Requester is 
installed. If the program is installed, Installation Check returns the components of 
the program that are installed. To determine which configuration the users specified 
when they started the network, perform the component checks in the order specified 
in the preceding assembler code. This order is required because a given 
configuration may install more than one component. 
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B809H (INT 2FH) 


Network Version Check 


Remarks 


&pegrule. 


Returns the version level of DOS LAN Requester. 


On Register 
Entry Contents 
On Register 
Return Contents 













A network installation check (AX = B800H), should be performed first to determine 


if the network has been installed. 


The Network Version Check function returns the hexadecimal equivalent of the DOS 


LAN Requester version. 


Appendix G. PC LAN Program 1.3 Compatibility 


G-11 


B80FH (INT2FH) 


Get Start Parameters 
&pegrule. 


Provides to the DOS application information on the start parameter values that are 
defined for the DOS LAN Requester. 


Entry Contents 


On Register 
Return Contents 
AX Zero: Network started 
Non-zero: Network not started 
CX Number of bytes returned in buffer 
unchanged if network not started 
ES:DI Start parameter value in buffer (see 
remarks) 


The data representing the start parameter will be placed in the buffer in the 
following format: 















Remarks 


DB O1H Major Version 
DB OOH Minor Version 
CONFIG Flags: If bit on, then the value was specified 
when the network was started. 


Bit 0 On = /NSV # O 

Bit 1 On = /NMS # O 

Bit 2 On = /API 

Bit 3 On = /HIM 

Bit 4 On = /LIM 

Bit 5 On = /ENC 

Bit 6 On = /POP 

Bit 7 On = /EMS 

Bit 8 On = /RPL 

Bits 9 - 12 Reserved 

Bit 13 On = RDR Started 

Bit 14 On = RCV Started 

Bit 15 On = User is currently logged on 
DB 15 DUP(' ') NET START Machine Name - blank padded 
DB Q ASCIIZ ended 
DB 9 OUP (0) NET START Domain Name - ASCIIZ ended 
DB QO Word Align 
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The following items are described in the description of the NET START command 
in the DOS LAN Requester User’s Guide.: 


DB 
DW 


32 DUP (' ') 
2 


DPD OD OND RD ORD OD ORD oD oD PD OND PND OD oD oD OND oD eo OND OND 


2 a8 
a | e 


127 DUP('?') 


/WRK ASCII numeric - blank padded 
/SRV 

/ASG 

/NBC 

/NBS 

/BBC 

/BBS 

/PBC 

/PBS 

/PFS 

/PFT 

/PWT 

/KUC 

/KST 

/NVS 

/NMS 

/NDB 

/MBI 

NETBIOS Machine Name Number 
NETBIOS Group Name Number 
Sessions Required for Configuration 
Commands Required for Configuration 
Names Required for Configuration 
NET START Path (LANROOT) 

ASCIIZ ended 
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Appendix H. LAN API Manifests 


This appendix lists the manifests associated with variable-length ASCIIZ strings that 
are pointed to by data structure components used in the OS/2 LAN API. The items 
listed under the Component column are either offsets to, or pointers to variable 
length ASCIIZ strings. These ASCIIZ strings can be from 0 to some maximum 
number of bytes long in most instances. The maximum length for the 
variable-length ASCIIZ strings is a manifest, or constant, that is defined with a value 
in the NETCONS.H header file. 


The variable length ASCIIZ string should not be greater in length than its 
manifest+ 1 bytes. The +1 is to allow for the ending NULL character of the string. 


The Manifest column lists the manifests defined in NETCONS.H. 


The Component column lists the data structure components that act as a pointer or 
are offset to a variable length ASCIIZ string. 


The Data Structure column lists the data structure of which the component is a 
member. 


The Category column lists the category to which the data structure belongs. 


The information is as follows: 


Manifest Component Data Structure Category 

CNLEN computername print_other_info Alert 
computername user_other_info Alert 
ae_so_compname ae_sesslogon Auditing 
ae_sf_compname ae_sesslogoff Auditing 
ae_sp_compname ae_sesspwerr Auditing 
ae_ct_compname ae_connstart Auditing 
ae_cp_compname ae_connstop Auditing 
ae_cr_compname ae_connrej Auditing 
ae_ra_compname ae_resaccess Auditing 
ae_rr_compname ae_resaccessrej Auditing 
ae_cf compname ae_closefile Auditing 
ae_am_compname ae_aclmod Auditing 
ae_um_compname ae_uasmod Auditing 
ae_no_compname ae_netlogon Auditing 
ae_nd compname ae_netlogondenied Auditing 
ae_al_ compname ae_acclim Auditing 
conil_netname connection_info_1 Connection 
wki0_computername wksta_info_0 Requester 
wki0_logon_server wksta_info_0 Requester 
wkil_computername wksta_info_1 Requester 
wkil_logon_server wksta_info_1 Requester 
wkil0_computername wksta_info_10 Requester 
sesil_cname session_info_1 Session 
sesi2_cname session_info_2 Session 
sesil0_cname session_info_10 Session 
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Manifest 


DEVLEN 


DNLEN 


MAXCOMMENTSZ 


MAXDEVENTRIES * 
(DEVLEN) 
MAXWORKSTATIONS 
* (CNLEN) 


NNLEN 


PATHLEN 


H-2 LAN Server Application Programmer’s Reference 


Component 


usri2_logon_server 
usril1_logon_server 
usrreq!_workstation 
usrreq2_computer 
usrlog2_computer 
ch0_dev 

chi_dev 

ui0_local 

uil_local 
wki0_langroup 
wkil_logon_domain 
wkil0_langroup 
wkil0_logon_domain 
usrlog!_domain 
grpil_comment 
svl_comment 
sv2_comment 
sv3_comment 
shil_remark 
shi2_remark 
usril_comment 
usri2_comment 
usril0_comment 
usril 1_comment 
usri2_full_name 
usrilO_full_name 
usril1_full_name 
usri2_usr_comment 
usrlog2_full_name 
usrlog2_usrcomment 
cql_devs 


usri2_workstations 


usril1_workstations 
ae_ct_netname 
ae_cp_netname 
ae_cr_netname 
cq0_dev 

cql_dev 
acc0O_resource_name 
accl_resource_name 
ae_ra_resname 
ae_rr_resname 
ae_cf_resname 
ae_am_resname 
ae_um_resname 
ae_al_resname 
fil_pathname 
fi3_pathname 


Data Structure 


user_info_2 
user_info_11 
user_logon_req_1 
user_logon_req_2 
user_logon_info_2 
chardev_info_0 
chardev_info_1 
use_info_0 
use_info_1 
wksta_info_0 
wksta_info_1 
wksta_info_10 
wksta_info_10 
user_logon_info_1 
group _info_1 
server_info_1 
server_info_2 
server_info_3 
share_info_1 
share_info_2 
user_info 1 
user_info_2 
user_info_10 
user_info_11 
user_info_2 
user_info_10 
user_info_11 
user_info 2 
user_logon_info_2 
user_logon_info_ 2 
chardevQ info_1 


user_info_2 


user_info_11 
ae_connstart 
ae_connstart 
ae_connrej 
chardevQ _info_0 
chardevQ_info_1 
access_info_0 
access_info_1 
ae_resaccess 
ae_resaccessrej 
ae_closefile 
ae_aclmode 
ae_uasmode 
ae_acclim 
file_info_1 
file_info_3 


Category 


User 
User 
User 
User 
User 
Serial Device 
Serial Device 
Use 

Use 
Requester 
Requester 
Requester 
Requester 
User 
Group 
Server 
Server 
Server 
Share 
Share 
User 

User 

User 

User 

User 
User 

User 

User 

User 

User 
Serial Device 


User 


User 
Auditing 
Auditing 
Auditing 
Serial Device 
Serial Device 
Access 
Access 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
File 

File 
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UNLEN 


RMLEN 


SNLEN 


WRKHEUR_COUNT 


Component 


wki0_root 

wkil_ root 
sv2_userpath 
sv3_userpath 
shi2_path 
usril_home_dir 
usril_script_path 
usri2_home_dir 
usri2_script_path 
usrill_home_dir 
usri2_parms 
usrill_parms 
usrlogl_script_path 
username 
username 
ae_sO_username 
ae_sf_ username 
ae_sp_username 
ae_ct_username 
ae_cp_username 
ae_cr_username 
ae_ra_username 
ae_1r_username 
ae_cf_username 
ae_ss_username 
ae_am_username 
ae_um_username 
ae_no_username 
ae_nd_username 
ae_al username 
conil_username 
fil_username 
fi3_username 
wki0_username 
wkil_username 
wkil0_username 
sesil_username 
sesi2_username 
sesil_username 
uid_remote 
uil_remote 
ae_ss_svcname 
wki0_wrkheuristics 
sv2_srvheuristics 
sv3_srvheuristics 


Data Structure 


wksta_info_0 
wksta_info_1 
server_info_2 
server_info 3 
share info 2 
user_info_1 
user_info_1 
user_info_2 
user_info_2 
user_info_11 
user_info_2 
user_info_1 
user_logon_info_1 
print_other_info 
user_other_info 
ae_sesslogon 
ae_sesslogoff 
ae_sesspwerr 
ae_connstart 
ae_connstop 
ae_connrej 
ae_resaccess 
ae_resaccessrej 
ae_closefile 
ae_servicestat 
ae_aclmod 
ae_uasmod 
ae_netlogon 
ae_netlogondenied 
ae_acclim 
connection_info_1 
file_info_1 
file_info 3 
wksta_info_0 
wksta_info 1 
wksta_info_10 
session_info_| 
session_info_2 
session_info_10 
use_info_0 
use_info_1 
ae_servicestat 
wksta_info_0 
server_info_2 
server_info_3 
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Category 


Requester 
Requester 
Server 
Server 
Share 
User 
User 
User 
User 
User 
User 
User 
User 
Alert 
Alert 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 
Auditing 


Connection 


File 
File 


Requester 


Requester 


Requester 


Session 
Session 
Session 
Use 

Use 
Auditing 


Requester 


Server 
Server 
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Glossary 


This glossary contains terms specific to the LAN Server 
version 1.2 Application Programmer’s Reference. 
Additional information can be found in the JBM 
Dictionary of Computing(SC20-1699). 


access permission record. The information describing 
how users or groups can access the shared resource of a 
server. It contains the net name of the resource, user 
names and group names, and permissions granted for 
each user name and group name. 


account. The record of a user on a server. A user must 
first have an account on a server to use any of the 
shared resources of the server. 


admin. A function requirement specifying that the 
calling process must have administrative privileges to 
execute the function. This requirement is listed in 
parentheses after each function with the requirement. 


alert. A notification of registered clients of a system 
event. OS/2 LAN Requester/Server provides a basic set 
of alerts. To add to them, use the Alert functions. 


alert table. A list of registered users and groups of 
users, known as clients, to be notified each time a 
defined system event occurs. Clients can be registered as 
mailslots or semaphores. 


Alerter service. See service. 


anonymous pipe. A one-way data storage buffer 
maintained in RAM and used for interprocess 
communications (IPC). See named pipe. 


API. See application programming interface. 


application. A program or set of programs that 
perform a task; for example, a payroll application. For 
the OS/2 LAN Server, see private application and public 
application. 


application programming interface (API). A 
formally-defined programming language interface 
between an IBM system control program or a licensed 
program and the user of a program. 


ASCIIZ string. A null-ended (\0) ASCII string; a 
common string type used with the C programming 
language. 


batch file. A file containing DOS commands organized 
for sequential processing while in DOS mode; files that 
are identified with a .BAT extension. For OS/2 mode, 

see command file. 


broadcast message. A message sent to all users on the 
local area network (LAN). 
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centralized logon server. The server that verifies the 
logon password of a user name in a centralized logon 
security system. 


client process. (1) A program that establishes a 
connection to (opens) a named pipe. (2) In Presentation 
Interface, a process that uses a service or dynamic link 
library. A process is a client of the service or library. 


command. (1) A request from a terminal for 
performance of an operation or execution of a program. 


command file. A file containing OS/2 commands 
organized for sequential processing while in OS/2 mode; 
files that have a .CMD file name extension. For DOS 
mode, see batch file. 


computer. For LAN purposes, a computer is either a 
requester or a server. A computer can have only one 
computer name by which it is known to OS/2 LAN 
Requester/Server. 


computer name. A name given a network requester or 
server. A computer name can be no longer than 
CNLEN bytes (as defined in the NETCONS.H include 
file). An example is: 


workstal 


communication device. A device connected to a serial 
communication port. When shared, a communication 
device is known by the name of the communication 
device queue to which it is connected. See also device 
name. 


configuration. (1) The task of defining the devices, 
features, parameters, and programs for a system. (2) 
The arrangement and relationship of the components in 
a system or network. 


connect. To redirect a local device name to a shared 
resource on a server. 


connection. A direct communication link from a local 
device to a shared resource on a server. 


continue. To restart a OS/2 LAN Requester/Server 
service or resource that was paused. See also pause. 


device. In OS\2 LAN Server, a drive (for files 
resources) or port (for printers and serial devices) that is 
assigned when a resource is used. See communication 
device, disk device, and device driver. 


device driver. The executable code needed to attach and 


use a device such as a display, printer, plotter, or 
communications adapter. See device 
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device name. A name assigned to identify a specific 
printer, disk drive, or other peripheral device. A device 
name can be no Jonger than DEVLEN bytes (as defined 
in NETCONS.H include file). Examples include: 


G: 
LPT5 


directory. A structure for organizing files into groups. 
A directory can contain files and subdirectories of files 
in the format \dir\...\filename.ext 


disk device. A device assigned a device name that 
stores information in the form of files. 


distributed logon security. A security system in which 
each server verifies user permissions. 


domain. A set of servers that allocates shared network 
resources within a single logical system. 


event. A particular defined state of the network or of a 
service (such as when a disk drive reaches its complete 
disk capacity). 


event name. A name of a particular type of system 
event, limited to EVLEN bytes (as defined in 
NETCONS.H). An example is: 


TONEALERT 


explicit connection. The establishing of a connection by 
means of the NetUseAdd function, where a local device 
name is redirected to the shared resource of a server. 


file name. (1) The name used by a program to identify 
a file. (2) The portion of the identifying name that 
precedes the extension. 


file handle. A binary value that represents an open file; 
used in all I/O operations. 


group. A logical organization of users that have IDs 
according to activity or resource access authority. 


group name. A name assigned to a particular set of 
user names. A group name can be no longer than 
GNLEN bytes (as defined in NETCONS.H). An 
example is: 


bus inessgrp 
handle. An arbitrary integer value that the OS/2 
program returns to a process to represent a system 


resource so that the process can return the value to the 
OS/2 program on subsequent calls to use the resource. 


implicit connection. The establishing of a connection to 
the shared resource of a server by specifying the UNC 
name of the resource. 


IPC. See interprocess communication. 
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interprocess communication (IPC). The ability of local 
and remcte processes to transfer data and messages 
among themselves; used to offer services to and receive 
services from other programs on the network. 


LAN. See local area network. 


LAN group. The set of computers to which a given 
computer belongs. A requester can belong to only one 
LAN group. 


LAN path name. A computer name followed by one or 
more directory names, then followed by a file name 
(such as \\print2\styles\info.zap). 


local computer. The computer where a user is working. 
See also remote. 


local area network (LAN). (1) Two or more computing 
units connected for local resource sharing. (2) A 
network in which communications are limited to a 
moderate-sized geographic area such as a single office 
building, warehouse, or campus, and that do not extend 
accross public rights-of-way. 


local device. A device physically attached to the local 
requester—that is, the drives in the computer and any 
machinery connected to its parts. This is a contrast to a 
remote device which the requester accesses with the 
LAN software. 


local device name. A name by which a device is known 
(for example, C:\ or LPT1). 


log. A file containing a historical list of information. 
With OS/2 LAN Requester/Server, several kinds of logs 
can be set up: an error log, statistical log, message log, 
and audit log. 


log off. To remove a user name and password from a 
requester. See also log on. 


log on. To enter a user name and password at a 
requester to enable access to the LAN. The user must 
log on at the beginning of each computer session. At the 
end of a work session, the user should log off. See also 


log off. 


logon script. A set of commands executed when a user 
logs on to a requester. 


logon security. A security and permissions system 
restricting who has access to the information, settings 
and devices of a LAN. 


mailslot. A buffer that can store or forward messages 
to users or applications. 


mailslot name. A name of a buffer that can receive 
messages. Mailslot names must be preceded by 
\mailslot\, as follows: 


\mailslot\name 


message. A buffer or file of data sent to a messaging 
alias. 


message forwarding. The ability to reroute messages 
intended for a user or application on one computer to a 
user or application on another computer. 


message logging. The process of saving all incoming 
messages to a file. 


messaging alias. A registered name that is used to 
receive messages. 


messenger service. See service. 


name. The label by which OS/2 LAN Requester/Server 
knows a user, a shared device and so forth. In the OS/2 
LAN Requester/Server documents there are references 
to user name, computer name, net name, device name, 
etc. In addition, most system directories require a 
pathname parameter that identifies the drive, directory, 
subdirectories and specific name that the LAN must 
follow to get from the local requester to the device that 
is to be accessed. 


named pipe. A data storage buffer that is maintained in 
RAM; used for interprocess communication (IPC). See 
anonymous pipe. 


netname. A name assigned a shared resource with 
which remote users and processes establish connections. 
A net name consists of a computer name and the path 
name of where the resource is located. A net name can 
be no longer than RMLEN bytes (as defined in 
NETCONS.H). An example is: 


\\server1\tools\excel 


network. A configuration of data processing devices 
and software connected for information interchange. 


network-aware application. An application that is 
implemented to use network resources to its benefit. 


password. A word owned by a user or shared resource 
to prohibit other users from accessing a specified 
resource. User passwords can be no longer than 
PWLEN bytes; Share passwords can be no longer than 
SHPWLEN bytes (both parameters are defined in 
NETCONS.H). Examples include: 


My_password 
JLD*BDP 


path. The path is the route that one device on a LAN 
takes to access a remote device. Path descriptions 
usually include a drive specification; a directory name 
(the root directory is specified with a backslash only (\)); 
and optional subdirectories, such as \bin\src). 


path name. A file specification that describes the route 
from the current directory on the local requester to the 
file, in the following format: 


devicename:\directory\subdirectory\...\filename 


A path name can be no longer than PATHLEN bytes 
(as defined in the NETCONS.H include file). A 
backslash (\) precedes each directory name and file 
name. For example: 


E:\BIN\USR\NETCONS .H 


is the path name to the NETCONS.H file in the user 
subdirectory of the bin directory on the E drive. To 
specify a path name on the local drive, forgo the drive 
name, beginning the path with \directory. 


pause. To suspend a OS/2 LAN Requester/Server 
service or function. See also continue. 


permission. The permission setting on a shared resource 
determines which users can use the resource. Permission 
is also used to refer to the user’s privileges. On the 
LAN, certain levels of permission can be set, giving the 
user various degrees of freedom in accessing devices and 
in reading or changing information. See permission 
levels. 


permission levels. The degree to which a user can use a 
shared resource. Three permission levels (Guest, User, 
and Administrator) are provided in the OS/2 LAN 
Requester/Server software. 


pipe. See anonymous pipe, named pipe. 


pipe name. The name given a buffer that allows two 
processes to communicate serially with each other. A 
pipe name must be preceded by \pipe\, as follows: 


\pipe\buffername 


print device. A device that copies data from a computer 
onto paper. A print device is known to OS/2 LAN 
Requester/Server by the name of the port to which it is 
connected. See device names for more information 
specifying a print device in a LAN routine. 


private application. An application maintained by an 
individual user and not available across a network. 
Contrast with public application. 


public application. An application maintained by the 
network administrator and shared with users on a 
network. Contrast with private application. 


queue. An orderly list of elements waiting to be 
processed. OS/2 LAN Requester/Server software 


supports. serial device queues and spooler queues. 


raise. To notify a user or application of a particular 
event. 
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raw read and write server message block (SMB) 
protocol. The protocol used when an incoming or 
outgoing packet contains only data and no SMB format 
is used. 


remote. A term describing any server, requester, or 
resource that is not located on the local computer where 
a process is executing. 


remote administration. Conducting administrative tasks 
such as sharing the resource of a server from a remote 
computer. 


requester. The computer from which a user or 
application is accessing server resources. 


resource. Any device, application, drive, or information 
on a server that can be accessed by a requester. 


separator page. A sheet of paper automatically added 
between documents printed by way of a printer queue, 
sometimes containing such information as name, date 
and time of job. 


serial device. Any hardware device that processes 
ASCII characters (such as a printer, modem, or FAX 
machine). 


serial device queue. A pool of serial devices. With serial 
device queues, an application communicates directly to 
the device, instead of submitting a job to the queue (as 
with spooled devices). 


server. A computer on a local area network that 
controls access to shared resources such as files, 
printers, and modems. 


server name. A name of a particular network server. A 
server name can be no longer than CNLEN bytes (as 
defined in NETCONS.H). An example is: 


serverl 
service. The programs that perform the primary 


functions of OS/2 LAN Requester/Server and related 


software. The OS/2 LAN Requester/Server services are: 
Service Purpose 


replicator Provides for file replication 


dlrinst Downloads code from servers to requesters 
requester Basic OS/2 LAN software 
Server Software to perform administrative tasks 


such as sharing resources or assigning 
permissions and privileges 


messenger Software to send messages 


netpopup Software to receive incoming messages 
alerter Software to notify of an event 
netrun Software to remotely execute programs 
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netlogon Software for centralized-logon server 


pcedosrpl Supports remote IPL of DOS requesters. 
service name. A name of a network service. A service 
name can be no longer than SNLEN bytes (as defined in 
NETCONS.H). An example is: 


NETPOPUP 


session. A link between a requester and a server. A 
session is established the first time a requester requests 
to use the resource of a server. 


share. To make a local resource available to remote 
users or other processes. Only local resources can be 
shared. 


shared resource. The resource of a server that can be 
accessed by a requester on the network. 


SMB. See raw read and write server message block 
protocol. 


spool file data type name. A spool file data type defines 
the type of print jobs that a printer queue can process. 
A spool file data type name can be no longer than 
DTLEN bytes (as defined in NETCONS.H). An 
example is: 


IBMQSTD 


spooler. A program that intercepts the data going to a 
device driver and writes it to disk. The data is later 
printed or plotted when the required device is available. 
A spooler prevents output from different sources from 
being intermixed. 


time stamp. A record of the time at which a system 
event occurred. Time stamps are figured on the basis of 
the LAN system clock as the number of seconds passed 
since January 1, 1970. Time stamps are used for 
statistics. 


use. To establish a connection from a local device to a 
shared resource. 


user name. The unique name assigned to each person 
granted access to a LAN system. To log onto a 
requester, the person must enter a user name and a 
self-assigned password (see also password). The system 
uses the user name to keep track of who is performing 
which operations. 


A user name can be no longer than UNLEN bytes (as 
defined in NETCONS.H). An example is: 


shannong 
UNC name. See Universal Naming Convention name. 


Universal Naming Convention (UNC) name. A name 
given to a device, computer, or resource under the UNC 


to allow users and applications access to the resource \\Server\drive\file.ext 
across the network. An example is: 
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index 


A 


access operations 3-9 
Access Permission category 
access permission record 3-2 
description 3-2 
functions 3-2 
NetAccessAdd 3-6 
NetAccessCheck 3-9 
NetAccessDel 3-12 
NetAccessEnum 3-15 
NetAccessGetInfo 3-18 
NetAccessGetUserPerms 3-22 
NetAccessSetInfo 3-25 
recursive searching 3-15 
resource permissions 3-4 
resource types 3-9, 3-12, 3-18, 3-22, 3-25 
types of access operations 3-9 
access permission record, definition 3-2, X-1 
Access Permissions category 
data structures 3-3 
functions 2-1 
resource types 3-3 


account 
ADMIN 3-110 
GUEST 3-11, 3-110 
USER 3-110 


account limit exceeded 3-57 
account, definition X-1 
admin, definition X-1 
ae_data structures 
access control list modification 3-53 
access denied 3-52 
access granted 3-51 
account limit exceeded 3-57 
connection rejected 3-50 
connection started 3-49 
connection stopped 3-49 
network logoff record 3-55 
network logon denied 3-56 
network logon record 3-55 
password error 3-48 
server status changes 3-46 
service status code or text changed 3-52 
session begins 3-46 
session ends 3-48 
user accounts subsystem modification 3-54 
Alert category 
data structures 
event 3-30 
fixed-length header 3-30 
description 3-29 
functions 2-2 
NetAlertRaise 
alert classes 3-34 
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Alert category (continued) 
NetAlertStart 
alert classes 3-37 
NetAlertStop 3-40 
alert event structures 
entry made to error log file 3-31 
network message received 3-31 
notify administrator of network event 3-32 
notify user of event 3-32 
print request completed 3-31 
alert table 
alert table, definitions X-1 
changing the internal size 3-29 
alert, definition 3-29, X-1 
anonymous pipe 3-192 
anonymous pipes 3-194 
anonymous pipe, definition X-1 
API data structures 
levels of detail 1-5 
sample data structures 1-6 
API naming convention 
category identifier 1-1 
Net or DOS keyword 1-1 
verb 1-1 
API requirements 
admin 1-8 
DOS 1-8 
local 1-8 
partially admin 1-8 
server 1-8 
API security scheme 
application programming interface 1-7 
remote protection 1-7 
user interface 1-7 
API verbs 
add 1-2 
Del 1-2 
Enum 1-3 
GetInfo 1-4 
SetInfo 1-4 
API, definition X-1 
application programming interface (API), 
definition X-1 
application, definition X-1 
ASCIIZ string, definition X-1 
asynchronous and trace flags 3-200 
audit log file 
setting maximum size 3-60 
Auditing category 
audit entry types 3-43, 3-45 
audit log file 3-43, 3-60 
data structures 
ae data 3-46 
fixed-length header 3-44 
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Auditing category (continued) 
description 3-43 
functions 2-2 
NetAuditClear 

backup file 3-58 
NetAuditRead 3-61 
NetAuditWrite 3-66 


batch file, definition X-1 
broadcast messages 3-158, 3-163, 3-166, X-1 


Cc 


calls, function G-1 
centralized logon server, definition X-1 
client process, definition 3-191, X-1 
client, definition 3-29 
command file, definition X-1 
command, definition X-1 
communication device handles 3-139 
communication device, definition X-1 
computer name, definition X-1 
computer, definition X-1 
Configuration category 
description 3-68 
functions 2-2 
IBMLAN.INI file 3-68 
NetConfigGetAll2 3-73 
NetConfigGet2 3-70 
configuration, definition X-1 
Connection category 
connection types 3-76 
connection, definition 3-76 
data structures 3-76 
description 3-76 
functions 2-2 
NetConnectionEnum 3-78 
connection status 3-370 
connection types 3-76 
connection, definition 3-76, X-1 
C/2 sample program  F-1 


D 


deny-none sharing mode 3-277 
deny-write sharing mode 
buffering for opened files 3-217, 3-274 
errors 3-219 
opening 3-275 
wrkheuristic parameter 3-219 
device driver, definition X-1 
device name connections 3-368 
device name, definition X-2 
device, definition X-1 
directory, definition X-2 
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disk device, definition X-2 
distributed logon security, definition X-2 
Domain category 
description 3-81 
functions 2-3 
NetGetDCName 3-82 
NetLogonEnum 3-85 
domain, definition X-2 
DOS LAN.INI file 
DosDeleteMailslot 3-148 
DosMailslotInfo 3-149 
DosMakeMailslot 3-150 
DosPeekMailslot 3-151 
DosReadMailslot 3-152 
DosWriteMailslot 3-154 
dynamic link libraries 1-7 


encryption 
buffering 3-217 
controlling logging of errors 3-216 
for opened files 3-217 
OS/2 LAN Server 3-216 
error codes 
audit log C-17 
error log C-17 
I/O C-16 
message server C-12 
remote C-17 
requester C-18 
serial device C-15 
server C-14 
Use C-12 
error log file 
Error Logging category 3-88 
setting maximum size 3-92, 3-98 
Error Logging category 
data structures 3-88 
description 3-88 
error log file 3-88 
functions 2-3 
NetErrorLogClear 
backup file 3-90 
NetErrorLogRead 3-93 
NetErrorLogWrite 3-97 
error types 
network service 3-88 
OS/2 internal 3-88 
OS/2 LAN Requester/Server internal 3-88 
event name, defintion X-2 
event, definition 3-29, X-2 
explicit connection, definition X-2 


FCB 
priority 3-273 


FCB (continued) 
searches 3-274 
server 3-273 
writing to 3-274 
File category 
data structures 3-99 
description 3-99 
functions 2-3 
NetFileClose2 3-101 
NetFileEnum2 3-104 
NetFileGetInfo 3-107 
File Control Block (FCB) 3-273 
file handle, definition X-2 
file name, definition X-2 
first-class mail 3-154 
first-class messages 3-147 
format of API reference pages 3-1 
function calls 
administrative, local, server 1-8 
local vs remote 1-8 
function categories 
Access Permissions 2-1 
Alert 2-2 
Auditing 2-2 
Configuration 2-2 
Connection 2-2 
Domain 2-3 
Error Logging 2-3 
File 2-3 
Group 2-3 
Handle 2-4 
Mailslot 2-4 
Message 2-5 
Named Pipe 2-5 
Remote Utility 2-7 
Requester 2-7 
Serial Device 2-7 
Server 2-8 
Service 2-8 
Session 2-8 
Share 2-9 
Spooler 2-9 
Statistics 2-10 
Use 2-10 
User 2-10 
function libraries B-1 
function requirements B-4 


G 


Group category 
data structures 3-111 
description 3-110 
functions 2-3 
NetGroupAdd 3-112 
NetGroupAddUser 3-115 
NetGroupDel 3-118 
NetGroupDelUser 3-121 


Group category (continued) 
NetGroupEnum 3-124 
NetGroupGetInfo 3-127 
NetGroupGetUsers 3-130 
NetGroupSetInfo 3-133 
NetGroupSetUsers 3-136 
special groups 3-110 

group name, definition X-2 

group, definition 3-110, X-2 

GUEST account 3-11 
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Handle category 
communication device handles 3-139 
data structures 3-139 
description 3-139 
functions 2-4 
named pipe handles 3-139 
NetHandleGetInfo 3-140 
NetHandleSetInfo 3-143 

handle, definition X-2 


I 
IBMLAN.INI file 
comment lines 3-68 
component lines 3-68 
definition 3-68 
parameter lines 3-68 
implicit connection, definition X-2 
include files A-1 
input/output controls (OCTLs) 3-277 
for large file transfers 3-278 
large (64KB) 3-278 
interprocess communication (IPC) 3-146, X-2 
IPC, definition X-2 


L 


LAN group, definition X-2 

LAN path name, definition X-2 

LAN, definition 

link-time libraries 
MAILSLOT.LIB- B-3 
NAMPIPES.LIB_ B-3 
NETAPI.LIB B-1 
NETOEM.LIB_ B-3 

local area network, definition X-2 

local computer, definition X-2 

local device name, definition X-2 

local device, definition X-2 

local mailslot 3-146 

log off, definition X-2 

log on, definition X-2 

logon script, definition X-2 

logon security, definition X-2 
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log, definition X-2 


Mailslot category 
description 3-146 
DosDeleteMailslot 3-148 
DosMailslotInfo 3-149 
DosMakeMailslot 3-150 
DosPeekMailslot 3-151 
DosReadMailslot 3-152 
DosWriteMailslot 3-154 
first-class mail 3-154 
first-class messages 3-147 
functions 2-4 
local and remote mailslots 3-146 
second-class mail 3-154 
second-class messages 3-147, 3-156 
mailslot name, definition X-2 
mailslot, definition X-2 
manifests 
Message category 
broadcast messages 3-158, 3-163, 3-166 
data structures 3-159 
description 3-157 
functions 2-5 
message log file 3-158 
messenger service 3-157 
NetMessageBufferSend 3-161 
NetMessageFileSend 3-164 
NetMessageLogFileGet 3-168 
NetMessageLogFileSet 3-170 
NetMessageNameAdd 3-173 
NetMessageNameDel 3-176 
NetMessageNameEnum 3-179 
NetMessageNameFwd 3-182 
NetMessageNameGetInfo 3-185 
NetMessageNameUnFwd 3-188 
message forwarding, definition X-3 
message log file 3-158 
message logging, definition X-3 
message, definition 3-157, X-3 
messaging alias, definition X-3 
messenger service 3-157 


Named Pipe category 
anonymous pipes 
description 3-191 
functions 2-5 
remote-procedure call (RPC) 3-193 
transition states 3-194 

named pipe handles 3-139 

named pipes 
buffering modes for read and write requests 
description 3-213, 3-214 _ 
for small read and write requests 3-214 


3-194 


3-214 
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named pipe, definition 3-191, X-3 
name, definition X-3 
NetAccessAdd 3-6 
NetAccessCheck 3-9 
NetAccessDel 3-12 
NetAccessEnum 3-15 
NetAccessGetInfo 3-18 
NetAccessGetUserPerms 3-22 
NetAccessSetInfo 3-25 
NetAlertRaise 3-34 
NetAlertStart 3-37 
NetAlertStop 3-40 
NetAuditClear 3-58 
NetAuditRead 3-61 
NetAuditWrite 3-66 
NetCharDevControl 3-243 
NetCharDevEnum 3-246 
NetCharDevGetInfo 3-248 
NetCharDevQEnum 3-251 
NetCharDevQGetInfo 3-254 
NetCharDevQPurge 3-257 
NetCharDevQPurgeSelf 3-260 
NetCharDevQSetInfo 3-263 
NetConfigGetAll2 3-73 
NetConfigGet2 3-70 
NetConnectionEnum 3-78 
NetErrorLogClear 3-90 
NetErrorLogRead 3-93 
NetErrorLogWrite 3-97 
NetFileClose 3-101 
NetFileEnum2 3-104 
NetFileGetInfo 3-107 
NetGetDCName 3-82 
NetGroupAdd 3-112 
NetGroupAddUser 3-115 
NetGroupDel 3-118 
NetGroupDelUser 3-121 
NetGroupEnum 3-124 
NetGroupGetInfo 3-127 


NetGroupGetUsers 3-130 
NetGroupSetInfo 3-133 
NetGroupSetUsers 3-136 


NetHandleGetInfo 3-140 
NetHandleSetInfo 3-143 
NetLogonEnum 3-85 
NetMessageBufferSend 3-161 
NetMessageFileSend 3-164 
NetMessageLogFileGet 3-168 
NetMessageLogFileSet 3-170 
NetMessageNameAdd 3-173 
NetMessageNameDel 3-176 
NetMessageNameEnum 3-179 
NetMessageNameFwd 3-182 
NetMessageNameGetInfo 3-185 
NetMessageNameUnFwd 3-188 
netname, definition X-3 
NetRemoteCopy 3-197 


NetRemoteExec 3-200 
NetRemoteMove 3-203 
NetRemoteTOD 3-206 
NetServerAdminCommand 3-284 
NetServerDiskEnum 3-287 
NetServerEnum2 3-289 
NetServergetinfo 3-292 
NetServerSetInfo 3-295 
NetServiceControl 3-310 
NetServiceEnum 3-314 
NetServiceGetInfo 3-317 
NetServicelnstall 3-320 
NetServiceStatus 3-323 
NetSessionDel 3-328 
NetSessionEnum 3-331 
NetSessionGetInfo 3-334 
NetShareAdd 3-340 
NetShareCheck 3-344 
NetShareDel 3-347 
NetShareEnum 3-350 
NetShareGetInfo 3-353 
NetShareSetInfo 3-356 
NetStatisticsGet2 3-365 
NetUseAdd 3-372 
NetUseDel 3-375 
NetUseEnum 3-378 
NetUseGetInfo 3-380 
NetUserAdd 3-397 
NetUserDel 3-401 
NetUserEnum 3-404 
NetUserGetGroups 3-407 
NetUserGetInfo 3-410 
NetUserModalsGet 3-413 
NetUserModalsSet 3-416 
NetUserPasswordSet 3-419 
NetWkstaGetInfo 3-225 
NetWkstaSetInfo 3-227 
NetWkstaSetUID2 3-231 
network logoff record 3-55 
network logon denied 3-56 
network logon record 3-55 
network name formats 1-9 
network service status 3-302, 3-303, 3-305, 3-306, 
3-307 

network-aware application, definition X-3 
network, definition X-3 
numworkbuf parameter 3-211 


O 


opportunistic lock timeout 3-276 
ordinal position 1-5 


Pp 


password error 3-48 
password, definition X-3 


path name, definition X-3 

path, definition X-3 

pause, definition X-3 

permission levels, definition X-3 
permission, definition X-3 

pipe name, definition X-3 

popup service 3-158 

primary error codes 3-303, 3-307 
print device, definition X-3 
private application, definition X-3 
process identification (PID) 3-202 
protocols 3-214 

public application, definition X-3 


Q 


queue, definition X-3 


R 


raise, definition X-3 
raw read and write SMB protocol, definition X-4 
read-ahead 3-215, 3-273 
recursive searching 3-15 
remote administration, definition X-4 
remote executable flags 3-201 
remote mailslot 3-146 
remote resource types 3-370 
Remote Utility category 
asynchronous and trace flags 3-200 
data structures 3-196 
description 3-196 
functions 2-7 
handles 3-202 
NetRemoteCopy 3-197 
NetRemoteExec 3-200 
NetRemoteMove 3-203 
NetRemoteTOD 3-206 
process identification (PID) 3-202 
remote executable flags 3-201 
return status of file move 3-204 
source and destination files 3-204 
remote-procedure call (RPC) 3-193 
remote, definition X-4 
Requester category 
data structures 3-208 
description 3-208, 3-211 
functions 2-7 
heuristics features 3-211 
NetWkstaGetInfo 3-225 
NetWkstaSetInfo 3-227 
NetWkstaSetUID2 3-231 
requester statistics 3-360 
requester, definition X-4 
resource, definition X-4 
return codes 
access C-9 
group C-9 


Index X-11 


return codes (continued) 
network utilities C-3 
redirector C-1 
requester C-8 
service C-7 
spooler C-5 
successful C-1 
user C-9 

run-time libraries B-4 


Ss 


sample program 
C/2 F-1 
scavenger 
buffering 3-274 
for opened files 3-274 
second-class mail 3-154 
second-class messages 3-147, 3-156 
secondary error codes 3-304, 3-308 
separator page, definition X-4 
Serial Device category 
data structures 3-240 
description 3-238 
functions 2-7 
NetCharDevControl 3-243 
NetCharDevEnum 3-246 
NetCharDevGetInfo 3-248 
NetCharDevQEnum 3-251 
NetCharDevQGetInfo 3-254 
NetCharDevQPurge 3-257 
NetCharDevQPurgeSelf 3-260 
NetCharDevQSetInfo 3-263 
serial device, definition 3-238 
serial device queue, definition X-4 
serial device, definition 3-238, X-4 
Server category 
data structures 3-267 
description 3-267 
functions 2-8 
heuristics features 3-272 
NetServerAdminCommand 3-284 
NetServerDiskEnum 3-287 
NetServerEnum2 3-289 
NetServergetinfo 3-292 
NetServerSetInfo 3-295 
server message block (SMB) protocols 
server name, definition X-4 
server process, definition 3-191 
server services 
creating D-1 
starting D-1 
stopping D-4 
server Statistics 3-363 
server status changes 
server, definition X-4 
Service category 
data structures 3-300 
service status 3-300 


3-214, 3-273 


3-46 
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Service category (continued) 
description 3-298 
functions 2-8 
NetServiceControl 3-310 
NetServiceEnum 3-314 
NetServiceGetInfo 3-317 
NetServiceInstall 3-320 
NetServiceStatus 3-323 
network service status 3-302, 3-303, 3-305, 3-306, 
3-307 
primary error codes 3-303, 3-307 
secondary error codes 3-304, 3-308 
standard network services 3-298 
service name, definition X-4 
service status code 3-52 
service, definition X-4 
Session category 
data structures 3-324 
description 3-324 
functions 2-8 
NetSessionDel 3-328 
NetSessionEnum 3-331 
NetSessionGetInfo 3-334 
session, definition X-4 
Share category 
component requirements 3-343 
data structures 3-337 
description 3-337 
functions 2-9 
NetShareAdd 3-340 
NetShareCheck 3-344 
NetShareDel 3-347 
NetShareEnum 3-350 
NetShareGetInfo 3-353 
NetShareSetInfo 3-356 
share types 3-338 
share types 3-338 
shared resource, definition X-4 
share, definition X-4 
sizreqbuf parameter 
description 3-212 
heuristics 3-212 
heuristics (requester) 3-212 
IBMLAN.INI fine-tuning options 3-212 
locking 3-212 
locking files 3-212 
opening 3-212 
Requester network service 3-212 


size 3-211 

tuning options 3-212 
SMB 

file transfers 3-214 

LAN 3-214 


SMB, definition X-4 
spool file data type name, definition 
Spooler category 

description 3-359 


Spooler function 
functions 2-9 
spooler, definition X-4 
srvannounce parameter 
description 3-272 
heuristics 3-272 
heuristics (server) 3-272 
IBMLAN.INI fine-tuning options 3-272 
Server network service 3-272 
tuning options 3-272 
srvnets parameter 
networks running on 3-278 
srvpipes parameter 
maximum per server 3-278 
srvservices parameter 
other server running on 3-278 
to start with server 3-278 
stack size, extending 1-8 
standard network services 
alerter 3-298 
messenger 3-298 
netlogon 3-299 
netpopup 3-299 
netrun 3-299 
requester 3-299 
server 3-299 
Statistics category 
data structures 3-360 
description 3-360 
functions 2-10 
NetStatisticsGet2 3-365 
requester statistics 3-360 
server statistics 3-363 
storing fixed-length and variable-length data 1-6 


T 
thread 3-273 
time stamp, definition X-4 
time-of-day information 3-206 
transferring files 
for large file transfers 3-276 
locking 3-276 


U 


universal naming convention (UNC) connections 3-368 
Universal Naming Convention (UNC) name, 
definition X-4 
Use category 
connection status 3-370 
data structures 3-369 
description 3-368 
device name connections 3-368 
disconnection types 3-375 
functions 2-10 
NetUseAdd 3-372 
NetUseDel 3-375 


Use category (continued) 
NetUseEnum 3-378 
NetUseGetInfo 3-380 
remote resource types 3-370 
universal naming convention (UNC) 
connections 3-368 
user accounts subsystem modification 3-54 
user accounts subsystem (UAS) 3-382 
User category 
data structures 3-385 
description 3-382 
DOS considerations 3-385 
functions 2-10 
NetUserAdd 3-397 
NetUserDel 3-401 
NetUserEnum 3-404 
NetUserGetGroups 3-407 
NetUserGetInfo 3-410 
NetUserModalsGet 3-413 
NetUserModalsSet 3-416 
NetUserPasswordSet 3-419 
NetUserSetGroups 3-423 
NetUserSetInfo 3-426 
NetUserValidate2 3-431 
user accounts subsystem (UAS) 3-382 
user name, definition X-4 
use, definition X-4 


V 

virtual circuits 
large (64KB) 3-276 
named 3-213 
named pipes 3-213 
NETBIOS 3-212 
number of 3-276 
printer requests 3-275 
serial devices 3-213 
sessions 3-212 
transfers 3-276 


W 


write-behind 
chain send command 3-273 
read-ahead 3-215 
write-behind 3-215, 3-273 
wrknets parameter 
names of networks running on 3-219 
wrkservices parameter 
other services started with 3-219 
to start with Requester service 3-219 
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